> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artificialstudio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Reference

> Every tool exposed by the Artificial Studio MCP server.

The MCP server exposes 6 tools. AI clients discover them automatically via `tools/list` — you don't call them directly; your AI does.

## `search_tools`

Find the right Artificial Studio tool for a task.

**Arguments**

| Name    | Type   | Description                                                        |
| ------- | ------ | ------------------------------------------------------------------ |
| `query` | string | Free-form description, e.g. `"generate image"`, `"text to speech"` |

**Returns**: `{ data: Tool[] }` with matching tools, each including input schemas and pricing.

**Example prompt**

> *"What tools does Artificial Studio have for making music?"*

***

## `get_tool_detail`

Get full details for one tool: all models, input schemas, pricing.

**Arguments**

| Name        | Type   | Description                                                            |
| ----------- | ------ | ---------------------------------------------------------------------- |
| `tool_slug` | string | Tool slug, e.g. `"create-image"`, `"create-video"`, `"text-to-speech"` |

**Returns**: the tool object with `models[]`, each with `slug`, `name`, `cost`, `costUnit`, and `inputSchema`.

Call this before `generate` if you want your AI to pick the best/cheapest model, or to show the user options.

***

## `generate`

Submit a generation job. **Returns immediately** with a `job_id` — the job runs asynchronously in the background.

<Warning>
  This tool is async. After calling, poll `check_generation` with the returned `job_id` every few seconds until `status` is `"success"` or `"error"`. Videos and audio can take minutes.
</Warning>

**Arguments**

| Name    | Type   | Description                                                              |
| ------- | ------ | ------------------------------------------------------------------------ |
| `tool`  | string | Tool slug, e.g. `"create-image"`                                         |
| `input` | object | Must include `model` (string) plus fields from the model's `inputSchema` |

**Example call**

```json theme={null}
{
  "tool": "create-image",
  "input": {
    "model": "flux-schnell",
    "prompt": "A cute golden retriever wearing sunglasses",
    "image_size": "square_hd"
  }
}
```

**Response**

```json theme={null}
{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "processing",
  "tool": "create-image",
  "type": "image",
  "eta_seconds": 15,
  "poll_after_seconds": 3,
  "message": "Job submitted. Poll check_generation with job_id=\"507f...\" every ~3s until status is \"success\" or \"error\"."
}
```

**Typical ETA hints**

| Type         | `eta_seconds` |
| ------------ | ------------- |
| image / text | 15            |
| audio        | 30            |
| 3d           | 60            |
| video (≤4s)  | 60            |
| video (8s)   | 120           |

`poll_after_seconds` is always clamped between **3s and 10s**.

***

## `check_generation`

Poll a generation by its `job_id`. Call this until `done: true`.

**Arguments**

| Name            | Type   | Description                  |
| --------------- | ------ | ---------------------------- |
| `generation_id` | string | The `job_id` from `generate` |

**Response — still running**

```json theme={null}
{
  "job_id": "507f...",
  "status": "processing",
  "tool": "create-image",
  "type": "image",
  "done": false,
  "poll_after_seconds": 5
}
```

**Response — success**

```json theme={null}
{
  "job_id": "507f...",
  "status": "success",
  "tool": "create-image",
  "type": "image",
  "output": "https://files.artificialstudio.ai/generations/abc123.png",
  "thumbnail": "https://files.artificialstudio.ai/thumbnails/abc123.jpg",
  "done": true
}
```

**Response — error**

```json theme={null}
{
  "job_id": "507f...",
  "status": "error",
  "tool": "create-image",
  "type": "image",
  "error": "Model failed: content policy violation",
  "done": true
}
```

<Note>
  `output` and `thumbnail` are only present on success. `error` is only present on failure. When `done: true`, stop polling.
</Note>

***

## `list_generations`

List recent generations from your account.

**Arguments**

| Name     | Type   | Default | Description                                         |
| -------- | ------ | ------- | --------------------------------------------------- |
| `limit`  | number | 20      | Items per page                                      |
| `offset` | number | 0       | Pagination offset                                   |
| `status` | string | —       | Filter: `pending`, `processing`, `success`, `error` |

Useful for "show me my last video" style prompts.

***

## `get_account`

Returns credits, plan, and basic account info for the authenticated user.

**Arguments**: none.

**Returns**

```json theme={null}
{
  "credits": 1234,
  "plan": "pro",
  "email": "you@example.com"
}
```

Your AI can use this to warn you before running expensive jobs.

***

## Error handling

Tool calls that fail throw standard MCP errors. Common causes:

| Error                              | Cause                                    |
| ---------------------------------- | ---------------------------------------- |
| `Tool 'X' not found`               | Invalid `tool_slug` or `tool` argument   |
| `Model 'X' not found for tool 'Y'` | `input.model` is wrong                   |
| `Insufficient credits`             | Charged in `generate` before queueing    |
| `Validation failed`                | `input` doesn't match the model's schema |
| `Generation not found`             | Wrong `job_id` in `check_generation`     |

Your AI will typically retry or ask you for clarification — behavior depends on the client.

## Next steps

<CardGroup cols={2}>
  <Card title="Async & polling" icon="clock" href="/mcp/async-polling">
    Deep dive on the async generation pattern.
  </Card>

  <Card title="Examples" icon="sparkles" href="/mcp/examples">
    Example prompts and conversations.
  </Card>
</CardGroup>