Skip to main content
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 endpoint return the same data in the same shape.

Annotations

Each tool carries tool annotations, which clients use to decide how much to ask you before a call. The read tools and run_agent are annotated differently:

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:
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
integer
default:"20"
Page size, 1-100.
string
Opaque cursor from a previous page’s next_cursor.
Example output
string
The brand’s id. Pass it as project_id to the other tools.
string
The tracked domain.
string
The brand’s name.
object
The tracking location: a location code (for example 2840 for the United States) and a language name.
string[]
AI engines tracked for this brand, such as chatgpt, perplexity, gemini, ai_overview, ai_mode, copilot and claude.
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
string
required
The brand’s id, from list_projects.
string
First day, YYYY-MM-DD. Defaults to 29 days before 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.
Example output
object[]
One point per day with a tracking run, oldest first. Days without a run are absent.
number
Visibility score, 0-100.
number
Share of answers that mention the brand, 0-1.
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
string
required
The brand’s id, from list_projects.
boolean
Only active (true) or only inactive (false) prompts. Both when omitted.
integer
default:"20"
Page size, 1-100.
string
Opaque cursor from a previous page’s next_cursor.
Example output
string | null
The prompt’s topic, when it has one.
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
string
required
The brand’s id, from list_projects.
string
Case-insensitive substring of the source domain, for example reddit or g2.com. Up to 253 characters.
integer
default:"20"
Page size, 1-100.
string
Opaque cursor from a previous page’s next_cursor.
Example output
integer
Times AI answers cited this page.
integer
How many times an engine’s web search retrieved the page, cited or not. At least times_cited where the engine reports retrievals.
string
When Quotable first saw the page.
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
string
required
The brand’s id, from list_projects.
string
First day, YYYY-MM-DD. Defaults to 29 days before to.
string
Last day, YYYY-MM-DD. Defaults to today (UTC).
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
string
required
The brand’s id, from list_projects.
string
required
The product title exactly as get_shopping_overview lists it.
string
First day, YYYY-MM-DD. Defaults to 29 days before 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, …).
This tool lists the brand’s article records. Documents that Quotable Agent writes into the Library aren’t included.
Scope: read:content
string
required
The brand’s id, from list_projects.
string
Only articles in this status. One of suggested, researching, outline, generating, polishing, awaiting_review, publishing, draft, published, publish_unknown, publish_quarantined.
integer
default:"20"
Page size, 1-100.
string
Opaque cursor from a previous page’s next_cursor.
Example output
The tool never returns article content. Use the REST API 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
string
required
The brand’s id, from list_projects.
string
Case-insensitive substring of the normalized term. Up to 200 characters.
integer
Only terms for this location, for example 2840 for the United States.
string
Only terms in this language, as a language name such as English.
integer
default:"20"
Page size, 1-100.
string
Opaque cursor from a previous page’s next_cursor.
Example output
string
ok, no_data or error.
integer | null
Estimated monthly AI question volume for period. null when no figure is available.
string | null
The month (YYYY-MM) the headline volume describes.
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
string
required
The brand’s id, from list_projects.
integer
default:"20"
Page size, 1-100.
string
Opaque cursor from a previous page’s next_cursor.
string
built_in for an agent that ships with Quotable, custom for one built in your workspace.
integer | null
The published version, or null while the agent only has a draft.
integer
How many times the agent has run.
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
string
required
The brand’s id, from list_projects.
string
required
The agent’s id, from list_agents.
object[]
What a run takes: each input’s key, label, type, required, hint and, for a dropdown, its options.
object[]
The steps in order, each with a name and type.
string
published or draft: which version a run uses.
string[]
Steps that act outside Quotable, such as posting to Slack or using a connected app.
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.
string
required
The brand’s id, from list_projects.
string
required
The agent’s id, from list_agents. Only agents that get_agent reports as runnable_via_api can run here.
object
default:"{}"
Input values keyed by each input’s key from get_agent. Values are text, numbers, booleans or lists of text.
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.
Example output
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
string
required
The brand’s id, from list_projects.
string
required
The agent’s id.
string
required
The run_id that run_agent returned.
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.
object[]
Each step’s name, status, credits and error.
string | null
The final result as text, once the run has ended. Long results are shortened.
object | null
The agent’s declared outputs, keyed as the agent names them.
number | null
Credits the run used.
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
string
required
The brand’s id, from list_projects.
integer
default:"20"
Page size, 1-100.
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
string
required
The brand’s id, from list_projects.
string
required
The table’s id, from list_tables.
string[]
Only these fields of each row, such as ["cells.Company", "cells.Summary"], to read only some columns.
integer
default:"20"
Page size, 1-100.
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:
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.

Next steps

Example prompts

Questions that put these tools to work.

Workflows

Multi-step recipes across tools.

Authentication

Scopes and brand limits for each key.
Last modified on November 18, 2026