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

# MCP tools

> Reference for the tools exposed by the Kettio MCP server.

Tools available once the [MCP server is connected](/mcp/installation). Schemas here match
`@kettio/mcp-server` v3.0.0.

<Note>
  Every ranking tool takes **local file paths** and handles the upload for you. Inside an MCP
  client there is no separate "publish to a URL" step — that only applies when you call the
  [REST API](/guides/rank-api) directly.
</Note>

## Choosing a ranking tool

<CardGroup cols={2}>
  <Card title="rank_assets" icon="bolt">
    Scores and returns the ranking in one call. Use it for interactive work where you want the
    answer immediately.
  </Card>

  <Card title="rank_ad_batch" icon="clock">
    Queues the work and returns a run ID straight away. Use it for large batches, or when
    blocking the agent for the whole scoring pass is not acceptable.
  </Card>
</CardGroup>

Both reach the same scoring pipeline and bill identically. The difference is whether you wait.

## rank\_assets

Runs Kettio's audience-fit model on 1–20 local ad creatives and returns the ranked winner, real
Kettio scores, confidence, rationale, and close-pair panel outcome.

| Parameter              | Type       | Required | Description                                                                                                   |
| ---------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `assets`               | `object[]` | Yes      | 1–20 creatives. Each needs `path`; optional `id` and `copyContext`.                                           |
| `assets[].path`        | `string`   | Yes      | Local path, relative to the workspace or absolute.                                                            |
| `assets[].id`          | `string`   | No       | Stable label such as `ad-1`.                                                                                  |
| `assets[].copyContext` | `object`   | No       | `pageName`, `adBody`, `adHeadline`, `adCaption`, `adDescription`. Enables full-package scoring and copy lift. |
| `audience`             | `string`   | Yes      | Concrete audience description — needs, objections, awareness, buying context.                                 |
| `audienceName`         | `string`   | No       | Short label shown in the result.                                                                              |
| `goal`                 | `string`   | No       | Defaults to `purchase-intent`.                                                                                |
| `platform`             | `string`   | No       | Placement context such as `facebook`, `instagram`, `tiktok`.                                                  |
| `assetType`            | `string`   | No       | Defaults to `Social Media Post`.                                                                              |
| `refineClosePairs`     | `boolean`  | No       | Pairwise panel on close scores. Defaults to `true`.                                                           |

## rank\_ad\_batch

Queues an asynchronous ranking run and returns a run ID immediately. Poll
[`get_rank_run`](#get-rank-run) to collect the result.

Takes the same parameters as `rank_assets`, plus:

| Parameter    | Type     | Required | Description                                                               |
| ------------ | -------- | -------- | ------------------------------------------------------------------------- |
| `audienceId` | `string` | No       | ID of a saved audience, from `list_audiences`. Use instead of `audience`. |
| `batchId`    | `string` | No       | Caller-owned label for this batch, echoed back on the run.                |

`audience` is required unless you supply `audienceId`.

## get\_rank\_run

Polls one run created by `rank_ad_batch`.

| Parameter | Type     | Required | Description                         |
| --------- | -------- | -------- | ----------------------------------- |
| `runId`   | `string` | Yes      | Run ID returned by `rank_ad_batch`. |

<Warning>
  Results are withheld until the whole batch finishes. A poll that returns `queued` or
  `processing` carries no ranking — it is not a partial answer to report from. Poll about every
  three seconds. Polling is never billed.
</Warning>

## list\_audiences

Lists saved audiences on the authenticated account, with their IDs.

| Parameter | Type     | Required | Description                                     |
| --------- | -------- | -------- | ----------------------------------------------- |
| `limit`   | `number` | No       | Maximum to return. Defaults to 50, maximum 200. |

Pass an ID as `audienceId` to `rank_ad_batch` to score against a saved audience instead of
retyping a description.

<Note>
  Creating, editing, and deleting audiences happens in the
  [Kettio dashboard](https://kettio.com/dashboard), not through this server. The MCP surface is
  read-only for audiences.
</Note>

## Workspace resolution

The server resolves relative paths against, in order:

1. `KETTIO_WORKSPACE_PATH` when set
2. `CLAUDE_PROJECT_DIR` when available (Claude Code)
3. The MCP process working directory

Set `KETTIO_WORKSPACE_PATH` explicitly if your agent runs from a different directory than the
repo holding the creatives.

## Related

<CardGroup cols={2}>
  <Card title="Agent setup" icon="robot" href="/quickstart/agent-setup">
    Install the ranking pipeline into a coding agent end to end.
  </Card>

  <Card title="Agent loop" icon="arrows-rotate" href="/guides/agent-loop">
    The generate → score → decide cycle, and when to drop to REST.
  </Card>
</CardGroup>