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 andrun_agent are annotated differently:
How the tools work together
Start withlist_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:
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
Example output
Fields
Fields
The tracking location: a location code (for example
2840 for the United States) and a language name.AI engines tracked for this brand, such as
chatgpt, perplexity, gemini, ai_overview, ai_mode, copilot and claude.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
The range can span at most 366 days, and from can’t be after to.
Example output
Fields
Fields
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.
list_prompts
List prompts. The prompts tracked for a brand, oldest first, each with its location and modelled demand score. Scope:read:visibility
Example output
Fields
Fields
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
Case-insensitive substring of the source domain, for example
reddit or g2.com. Up to 253 characters.Example output
Fields
Fields
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
How many of the most recommended products to include, 1-50. This isn’t a page: the result has no cursor.
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 fromget_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
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.
read:content
Only articles in this status. One of
suggested, researching, outline, generating, polishing, awaiting_review, publishing, draft, published, publish_unknown, publish_quarantined.Example output
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
Example output
Fields
Fields
list_agents
List agents. A brand’s agents, newest first: name, description, whether a version is published, and how often it has run. Callget_agent for one agent’s inputs before running it.
Scope: read:agents
Fields
Fields
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
Fields
Fields
What a run takes: each input’s
key, label, type, required, hint and, for a dropdown, its options.run_agent
Run an agent. Starts a run of an agent with the given inputs and returns itsrun_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.
The agent’s id, from
list_agents. Only agents that get_agent reports as runnable_via_api can run here.Input values keyed by each input’s
key from get_agent. Values are text, numbers, booleans or lists of text.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
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
Fields
Fields
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.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
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
Only these fields of each row, such as
["cells.Company", "cells.Summary"], to read only some columns.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.