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

# Tools

> Reference for the Quotable MCP tools: what each returns, its inputs and defaults, the scope it needs, which one changes anything, and example output.

The Quotable MCP server exposes 14 tools. Thirteen of them only read data. One, `run_agent`, starts an agent run, which uses your workspace's credits; it needs the `run:agents` scope. No tool deletes or overwrites anything. Tools that have a matching [REST API](https://docs.usequotable.com/api-reference/introduction.md) endpoint return the same data in the same shape.

| Tool | Title | Scope | Returns |
| - | - | - | - |
| `list_projects` | List brands | `read:projects` | The brands the key can read |
| `get_visibility` | Get visibility series | `read:visibility` | Daily score, mention rate and share of voice |
| `list_prompts` | List prompts | `read:visibility` | Tracked prompts with location and demand score |
| `list_citations` | List cited sources | `read:visibility` | Pages AI answers cite, most cited first |
| `get_shopping_overview` | Get ChatGPT shopping overview | `read:visibility` | Products ChatGPT recommends for the brand's prompts |
| `get_shopping_product` | Get one shopping product | `read:visibility` | How one shopping product performs |
| `list_articles` | List articles | `read:content` | Articles and their status, without content |
| `search_demand` | Search demand terms | `read:demand` | Demand terms with monthly AI volume |
| `list_agents` | List agents | `read:agents` | The brand's agents |
| `get_agent` | Get an agent | `read:agents` | One agent's inputs and steps |
| `get_agent_run` | Get an agent run | `read:agents` | A run's status and, once it ends, its result |
| `run_agent` | Run an agent | `run:agents` | Starts a run and returns its id |
| `list_tables` | List tables | `read:tables` | The brand's tables |
| `get_table_rows` | Read table rows | `read:tables` | A page of a table's rows |

## Annotations

Each tool carries [tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools), which clients use to decide how much to ask you before a call. The read tools and `run_agent` are annotated differently:

| Annotation | Read tools | `run_agent` | Meaning |
| - | - | - | - |
| `readOnlyHint` | `true` | `false` | Whether the tool only reads. `run_agent` starts a run, so most clients ask you before calling it. |
| `destructiveHint` | `false` | `false` | No tool deletes or overwrites anything. |
| `idempotentHint` | `true` | `false` | Reading again has no extra effect. Calling `run_agent` again starts another run, unless you repeat its `idempotency_key`. |
| `openWorldHint` | `false` | `false` | Tools work only inside your Quotable workspace. |

## How the tools work together

Start with `list_projects`. Every other tool takes a `project_id`, which is a brand's id from that list. The server tells clients this in its instructions, so most assistants call `list_projects` first on their own.

The list tools return one page at a time:

```json theme={"system"}
{
  "data": [ … ],
  "next_cursor": "eyJ…"
}
```

Pages hold 20 items by default and up to 100 with `limit`. When `next_cursor` isn't `null`, pass it back as `cursor`, with the same filters, to get the next page. Cursors are opaque; don't build or edit them.

List tools also take `fields`: the fields to keep in each item, as dotted paths such as `["url", "times_cited"]` or `["cells.Summary"]`. Every other field is left out, which keeps long pages short. A path that matches nothing is ignored, and `next_cursor` always comes back.

Each result arrives twice: as JSON text in `content` and as an object in `structuredContent`. Clients use whichever they support.

## list\_projects

**List brands.** Lists the brands (tracked domains) this key may read, oldest first. Start here: every other tool takes a project\_id from this list.

Scope: `read:projects`

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

```json Example output theme={"system"}
{
  "data": [
    {
      "id": "3f1c2a9e-8b7d-4c61-9a2e-5d4b3c2a1f00",
      "name": "Acme",
      "domain": "acme.com",
      "brand_name": "Acme",
      "market": { "location_code": 2840, "language": "English" },
      "engines": ["chatgpt", "ai_overview", "ai_mode", "gemini"],
      "paused": false,
      "created_at": "2026-03-02T14:05:11.000Z"
    }
  ],
  "next_cursor": null
}
```

> [accordion] Fields
>
> **id** `string`
>
> The brand's id. Pass it as `project_id` to the other tools.
>
> **domain** `string`
>
> The tracked domain.
>
> **brand\_name** `string`
>
> The brand's name.
>
> **market** `object`
>
> The tracking location: a location code (for example `2840` for the United States) and a language name.
>
> **engines** `string[]`
>
> AI engines tracked for this brand, such as `chatgpt`, `perplexity`, `gemini`, `ai_overview`, `ai_mode`, `copilot` and `claude`.
>
> **paused** `boolean`
>
> `true` when tracking is suspended. History stays readable.

**Try:** "Which brands can you see in Quotable, and which engines does each one track?"

## get\_visibility

**Get visibility series.** Daily AI visibility for one brand over a date range: score (0-100), mention rate and normalized share of voice across every brand named in answers. Defaults to the last 30 days; at most 366.

Scope: `read:visibility`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**from** `string`

First day, `YYYY-MM-DD`. Defaults to 29 days before `to`.

**to** `string`

Last day, `YYYY-MM-DD`. Defaults to today (UTC).

The range can span at most 366 days, and `from` can't be after `to`.

```json Example output theme={"system"}
{
  "project_id": "3f1c2a9e-8b7d-4c61-9a2e-5d4b3c2a1f00",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "data": [
    {
      "date": "2026-09-01",
      "score": 42.5,
      "mention_rate": 0.38,
      "share_of_voice": { "Acme": 0.31, "Globex": 0.27, "Initech": 0.18, "Umbrella": 0.24 }
    },
    {
      "date": "2026-09-02",
      "score": 44.1,
      "mention_rate": 0.4,
      "share_of_voice": { "Acme": 0.33, "Globex": 0.25, "Initech": 0.19, "Umbrella": 0.23 }
    }
  ]
}
```

> [accordion] Fields
>
> **data** `object[]`
>
> One point per day with a tracking run, oldest first. Days without a run are absent.
>
> **data\[].score** `number`
>
> Visibility score, 0-100.
>
> **data\[].mention\_rate** `number`
>
> Share of answers that mention the brand, 0-1.
>
> **data\[].share\_of\_voice** `object`
>
> Every brand named in answers, tracked or discovered, mapped to its normalized share of voice, 0-1. Values sum to 1 when any brand is named.

**Try:** "Compare my visibility score for the first and second half of September, and tell me which competitor gained the most share of voice."

## list\_prompts

**List prompts.** The prompts tracked for a brand, oldest first, each with its location and modelled demand score.

Scope: `read:visibility`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**active** `boolean`

Only active (`true`) or only inactive (`false`) prompts. Both when omitted.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

```json Example output theme={"system"}
{
  "data": [
    {
      "id": "8a6f0d2b-1c3e-4f5a-9b7c-2d1e0f3a4b5c",
      "text": "What is the best project management tool for small agencies?",
      "topic": "Project management",
      "active": true,
      "market": { "location_code": 2840, "language": "English" },
      "demand_score": 71,
      "created_at": "2026-03-02T14:09:40.000Z"
    }
  ],
  "next_cursor": "eyJ…"
}
```

> [accordion] Fields
>
> **topic** `string | null`
>
> The prompt's topic, when it has one.
>
> **demand\_score** `integer | null`
>
> Modelled topic demand, 0-100. `null` when not computed.

**Try:** "List my active prompts grouped by topic, and flag the ones with the highest demand score."

## list\_citations

**List cited sources.** Pages AI answers cite for a brand's prompts, most cited first. Filter by a substring of the source domain.

Scope: `read:visibility`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**domain** `string`

Case-insensitive substring of the source domain, for example `reddit` or `g2.com`. Up to 253 characters.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

```json Example output theme={"system"}
{
  "data": [
    {
      "id": "c2b1a0f9-e8d7-4c6b-a5f4-e3d2c1b0a9f8",
      "url": "https://www.example-reviews.com/best-project-management-software",
      "domain": "example-reviews.com",
      "times_cited": 57,
      "times_retrieved": 112,
      "first_seen": "2026-03-04T06:12:00.000Z",
      "last_seen": "2026-09-30T05:47:00.000Z"
    }
  ],
  "next_cursor": "eyJ…"
}
```

> [accordion] Fields
>
> **times\_cited** `integer`
>
> Times AI answers cited this page.
>
> **times\_retrieved** `integer`
>
> How many times an engine's web search retrieved the page, cited or not. At least `times_cited` where the engine reports retrievals.
>
> **first\_seen** `string`
>
> When Quotable first saw the page.
>
> **last\_seen** `string`
>
> When Quotable last saw the page.

**Try:** "Which 20 pages do AI answers cite most for my prompts? Mark the ones on my own domain."

## get\_shopping\_overview

**Get ChatGPT shopping overview.** Which products ChatGPT recommends in its shopping carousel for one brand's prompts: how often a carousel appeared, the most recommended products (yours, competitors' and others') with their share, slot-1 rate and average slot, the retailers selling them, prompts a competitor wins that the brand is missing from, and searches rising against the previous period. ChatGPT only. Percentages are 0-100.

Scope: `read:visibility`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**from** `string`

First day, `YYYY-MM-DD`. Defaults to 29 days before `to`.

**to** `string`

Last day, `YYYY-MM-DD`. Defaults to today (UTC).

**max\_products** `integer` (default: 15)

How many of the most recommended products to include, 1-50. This isn't a page: the result has no cursor.

The tool is available when your plan includes Shopping. On a workspace without it, the tool answers `not_found`, as it does for a brand the key can't read.

**Try:** "Which products does ChatGPT recommend most for my prompts, and where is a competitor winning a carousel I'm missing from?"

## get\_shopping\_product

**Get one shopping product.** One product from the ChatGPT shopping carousel, by its exact title from `get_shopping_overview`: visibility, slot-1 rate, average slot and appearances against the previous period, rating, median quoted price, the prompts it wins and loses, the retailers selling it, the products that outrank it, attributes rivals were judged on and it wasn't, and prompts its usual shelf-mates appear in without it.

Scope: `read:visibility`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**title** `string` *required*

The product title exactly as `get_shopping_overview` lists it.

**from** `string`

First day, `YYYY-MM-DD`. Defaults to 29 days before `to`.

**to** `string`

Last day, `YYYY-MM-DD`. Defaults to today (UTC).

When the product wasn't shown in the range, the result has `"found": false` and the title you sent.

**Try:** "For our best-selling product in ChatGPT's carousel, which products outrank it and on which prompts does it lose?"

## list\_articles

**List articles.** A brand's articles without their content, newest first. Filter by status (draft, published, …).

> [!NOTE]
>
> This tool lists the brand's article records. Documents that Quotable Agent writes into the Library aren't included.

Scope: `read:content`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**status** `string`

Only articles in this status. One of `suggested`, `researching`, `outline`, `generating`, `polishing`, `awaiting_review`, `publishing`, `draft`, `published`, `publish_unknown`, `publish_quarantined`.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

```json Example output theme={"system"}
{
  "data": [
    {
      "id": "5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170",
      "title": "How small agencies choose a project management tool",
      "status": "published",
      "format": "buying_guide",
      "target_prompt": "What is the best project management tool for small agencies?",
      "target_prompt_id": "8a6f0d2b-1c3e-4f5a-9b7c-2d1e0f3a4b5c",
      "published_url": "https://acme.com/blog/agency-project-management",
      "published_at": "2026-09-12T09:00:00.000Z",
      "scheduled_for": null,
      "created_at": "2026-09-08T16:22:03.000Z",
      "updated_at": "2026-09-12T09:00:04.000Z"
    }
  ],
  "next_cursor": null
}
```

The tool never returns article content. Use the [REST API](https://docs.usequotable.com/api-reference/introduction.md) to read an article's HTML.

**Try:** "Which of my articles are still in draft or awaiting review, and which prompts do they target?"

## search\_demand

**Search demand terms.** The AI-volume demand terms behind a brand's prompts with their monthly series, alphabetical. Returns terms Quotable has already measured; reading them never starts new research. Filter by a substring of the term.

Scope: `read:demand`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**q** `string`

Case-insensitive substring of the normalized term. Up to 200 characters.

**location\_code** `integer`

Only terms for this location, for example `2840` for the United States.

**language** `string`

Only terms in this language, as a language name such as `English`.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

```json Example output theme={"system"}
{
  "data": [
    {
      "id": "0f9e8d7c-6b5a-4493-8271-605f4e3d2c1b",
      "term": "project management for agencies",
      "normalized": "project management for agencies",
      "market": { "location_code": 2840, "language": "English" },
      "status": "ok",
      "ai_volume": 14800,
      "period": "2026-08",
      "fetched_at": "2026-09-03T02:10:00.000Z",
      "months": [
        { "month": "2026-07", "ai_volume": 13900, "observed_at": "2026-08-02T02:11:00.000Z" },
        { "month": "2026-08", "ai_volume": 14800, "observed_at": "2026-09-03T02:10:00.000Z" }
      ]
    }
  ],
  "next_cursor": null
}
```

> [accordion] Fields
>
> **status** `string`
>
> `ok`, `no_data` or `error`.
>
> **ai\_volume** `integer | null`
>
> Estimated monthly AI question volume for `period`. `null` when no figure is available.
>
> **period** `string | null`
>
> The month (`YYYY-MM`) the headline volume describes.
>
> **months** `object[]`
>
> Up to twelve months, oldest first.

**Try:** "Which demand terms behind my prompts have the highest AI volume, and which are growing month over month?"

## list\_agents

**List agents.** A brand's agents, newest first: name, description, whether a version is published, and how often it has run. Call `get_agent` for one agent's inputs before running it.

Scope: `read:agents`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

> [accordion] Fields
>
> **kind** `string`
>
> `built_in` for an agent that ships with Quotable, `custom` for one built in your workspace.
>
> **published\_version** `integer | null`
>
> The published version, or `null` while the agent only has a draft.
>
> **run\_count** `integer`
>
> How many times the agent has run.
>
> **last\_run\_at** `string | null`
>
> When it last ran.

The agent tools work when Agents are turned on for your workspace. Otherwise they answer `unavailable`.

## get\_agent

**Get an agent.** One agent: the inputs a run needs, its steps in order, and whether it can be run from here.

Scope: `read:agents`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**agent\_id** `string` *required*

The agent's id, from `list_agents`.

> [accordion] Fields
>
> **inputs** `object[]`
>
> What a run takes: each input's `key`, `label`, `type`, `required`, `hint` and, for a dropdown, its `options`.
>
> **steps** `object[]`
>
> The steps in order, each with a `name` and `type`.
>
> **runs** `string`
>
> `published` or `draft`: which version a run uses.
>
> **external\_steps** `string[]`
>
> Steps that act outside Quotable, such as posting to Slack or using a connected app.
>
> **runnable\_via\_api** `boolean`
>
> `false` when the agent has external steps. Such an agent runs only from the app, where a person starts it.

## run\_agent

**Run an agent.** Starts a run of an agent with the given inputs and returns its `run_id` at once. The run happens in the background and uses your workspace's credits. Poll `get_agent_run` for the result.

Scope: `run:agents`. This is the only tool that changes anything. It's annotated as a write tool, so most clients ask you before each call.

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**agent\_id** `string` *required*

The agent's id, from `list_agents`. Only agents that `get_agent` reports as `runnable_via_api` can run here.

**inputs** `object` (default: \{})

Input values keyed by each input's `key` from `get_agent`. Values are text, numbers, booleans or lists of text.

**idempotency\_key** `string`

Any unique string for this call, 8-255 characters. Repeating it returns the first run instead of starting another, and `replayed` is `true`. Reusing it with different inputs answers `conflict`.

```json Example output theme={"system"}
{
  "run_id": "6b1e0c4d-2f3a-4b5c-8d7e-9f0a1b2c3d4e",
  "agent_id": "…",
  "status": "queued",
  "runs": "published",
  "version": 3,
  "steps": [ … ],
  "replayed": false
}
```

A run is refused with `forbidden` when the agent acts outside Quotable, or when the person who created the key or approved the connection has left the workspace or can no longer edit the brand. Starting many runs in a short time answers `rate_limited`.

## get\_agent\_run

**Get an agent run.** A run's status, its steps and, once it has ended, its result, outputs and credits used.

Scope: `read:agents`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**agent\_id** `string` *required*

The agent's id.

**run\_id** `string` *required*

The `run_id` that `run_agent` returned.

> [accordion] Fields
>
> **status** `string`
>
> `queued`, `running`, `paused`, `succeeded`, `failed` or `aborted`. A run is `paused` while it waits for someone to approve a step in the app, and `waiting_for_review` is then `true`.
>
> **steps** `object[]`
>
> Each step's `name`, `status`, `credits` and `error`.
>
> **result** `string | null`
>
> The final result as text, once the run has ended. Long results are shortened.
>
> **outputs** `object | null`
>
> The agent's declared outputs, keyed as the agent names them.
>
> **credits** `number | null`
>
> Credits the run used.
>
> **error** `string | null`
>
> Why the run failed, when it did.

**Try:** "List my agents, show me what inputs the competitor research agent needs, and run it for Globex." Your client asks before it calls `run_agent`.

## list\_tables

**List tables.** A brand's tables (sheets of rows with agent columns), last edited first, with their row and column counts.

Scope: `read:tables`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

Each item has `id`, `name`, `description`, `row_count`, `column_count`, `updated_at` and `created_at`.

## get\_table\_rows

**Read table rows.** A page of a table's rows in table order, each cell as text keyed by column name. Long cells are shortened.

Scope: `read:tables`

**project\_id** `string` *required*

The brand's id, from `list_projects`.

**table\_id** `string` *required*

The table's id, from `list_tables`.

**fields** `string[]`

Only these fields of each row, such as `["cells.Company", "cells.Summary"]`, to read only some columns.

**limit** `integer` (default: 20)

Page size, 1-100.

**cursor** `string`

Opaque cursor from a previous page's `next_cursor`.

The result also names the `table` and lists its `columns`, each with an `id`, a `name` and a `kind`: `data` (from the table's source), `input` (typed by a person), `workflow` (an agent's run status) or `output` (what that agent wrote).

**Try:** "Read the Company and Summary columns of my competitor table and list the companies whose summary mentions pricing."

## Errors

A tool that can't answer returns a normal result with `"isError": true` and a text message in the form `<code>: <message>`. The same code and message are in `structuredContent` as `error` and `message`:

```json theme={"system"}
{
  "content": [
    { "type": "text", "text": "not_found: No such brand in this workspace, or the key's project allowlist does not include it." }
  ],
  "structuredContent": {
    "error": "not_found",
    "message": "No such brand in this workspace, or the key's project allowlist does not include it."
  },
  "isError": true
}
```

| Code | When | Message |
| - | - | - |
| `insufficient_scope` | The key wasn't granted the tool's scope. | This tool requires the `<scope>` scope, which the key was not granted. |
| `not_found` | The brand doesn't exist, or the key's brand list excludes it. For the agent and table tools, also an agent, run or table the brand doesn't have. | No such brand in this workspace, or the key's project allowlist does not include it. / No such agent for this brand. |
| `invalid_parameter` | A value is valid in form but not in meaning, such as `from` after `to`. | For example: `` `from` must not be after `to`. `` or "The range may span at most 366 days." |
| `invalid_cursor` | The cursor wasn't issued by this server. | The cursor is not one this server issued; start from the first page. |
| `unavailable` | Agents aren't turned on for the workspace. | Agents are not enabled for this workspace. |
| `forbidden` | `run_agent` can't start this run: the agent acts outside Quotable, or the credential's creator left or can't edit the brand. | The message says which. |
| `rate_limited` | Too many runs started with this credential in a short time. | The message says when to try again. |
| `conflict` | An `idempotency_key` was reused with different inputs. | The message explains the conflict. |
| `internal` | Something failed on Quotable's side. | Something failed on our side. Request id `<id>`. |

Inputs that don't match a tool's schema, such as a `project_id` that isn't a UUID or a `limit` over 100, are rejected before the tool runs, with a message that starts `MCP error -32602: Input validation error: Invalid arguments for tool <name>`. A tool name that doesn't exist returns `MCP error -32602: Tool <name> not found`.

Errors that stop a request before any tool runs, such as an invalid key or the rate limit, are HTTP errors. See [Troubleshooting](https://docs.usequotable.com/mcp-server/troubleshooting.md).

## Next steps

> [card] [Example prompts](https://docs.usequotable.com/mcp-server/example-prompts.md)
>
> Questions that put these tools to work.

> [card] [Workflows](https://docs.usequotable.com/mcp-server/workflows.md)
>
> Multi-step recipes across tools.

> [card] [Authentication](https://docs.usequotable.com/mcp-server/authentication.md)
>
> Scopes and brand limits for each key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.