Getting started

Using the tools

What a tool returns, how failures look, what calls cost, and the one tool that spends money.

What a tool returns

Tools answer with structured output — the same object the matching REST endpoint returns — alongside the JSON as text, so clients that only read text still get everything.

tools/call result

{
  "content": [{ "type": "text", "text": "…the same JSON, as text…" }],
  "structuredContent": {
    "projects": [
      { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "Acme Invoicing", "industry": "Accounting software" }
    ]
  },
  "isError": false
}

Each tool’s page in the sidebar lists its arguments and every field of its result, with a link to the REST endpoint it mirrors.

When a tool fails

A failure comes back as a tool error — isError: true with the reason as text, in the form code: message. The codes are the API’s codes, so the error table applies here too.

{
  "content": [
    {
      "type": "text",
      "text": "write_not_allowed: This credential is read-only. Writes need a read-and-write key on the Scale or Custom plan."
    }
  ],
  "isError": true
}

A credential that is genuine but not entitled still connects, and every tool answers with the reason. That is deliberate: an assistant told plan_requiredcan explain what to do, while one told “unauthorized” tends to start the sign-in dance again.

Read, write and spend

Every tool is annotated so a client knows what it is agreeing to before it calls:

Kind	Annotation	Tools
Read	read-only	Everything named `list_…` or `get_…`
Write	not read-only, not destructive, idempotent	`add_prompts`, `update_prompt`, `set_content_asset_state`, `set_ticket_status`
Spends a credit	not read-only, not idempotent	`generate_draft`

Nothing here deletes anything. There is no tool to delete a prompt, publish to a CMS or start a probe run — see what the API deliberately can’t do.

The one tool that spends money

generate_draft consumes one of the month’s content credits. It takes two arguments that exist to keep that deliberate:

confirm_credit must be true. Without it, nothing is spent and the tool answers confirmation_required — the assistant should ask you first.
idempotency_key is your own string for this attempt. Reusing it returns the original generation instead of spending a second credit, so a retry after a timeout is safe.

Drafting is asynchronous: the tool returns a pending generation, and the text arrives through get_draft. Check get_plan_usage for how many credits are left before you start.

What calls cost

MCP shares the API’s per-minute budget — 60 on Grow, 300 on Scale, 600 on Custom, pooled across every key and connection on the plan. Most tools spend one unit; the ones that read a project’s whole history spend more: get_impact 5, get_competitor_analysis and get_platform_detail 3, get_visibility_trend and list_gaps 2. Rate limits has the details.

Reading the numbers correctly

Three conventions catch assistants out. They are worth saying in your own prompt as well:

Scores and rates are 0–100, with one exception: a single answer’s quality is 0–1, and 0.5 or more counts as a win.
Don’t compare across score_version values. When the scoring changes the version changes; a chart that mixes them shows a step nobody caused.
A window is anchored to the newest run, not to today, and a null win rate means too few shared answers to say — not zero.