# Tool reference

Every MCP tool, the inputs it takes and the gateway read or action it maps to.

> **Planned design**: The MCP server described here is the planned design layered on top of the agency REST gateway, which is live today. Until the server ships, everything on this page can be done with the REST endpoints in the API section.

Tools come in two families. **Read tools** wrap `GET ?resource=…&client_id=…` and return rows plus a pagination cursor. **Action tools** wrap `POST` with an `action` field and either return a result or a job reference for work that runs in the background.

## Read tools

| Tool | Inputs | Returns |
| --- | --- | --- |
| `list_clients` | `limit`, `cursor` | Clients the key can reach, with website and status. |
| `get_client` | `client_id` | One client record with its settings and connected integrations. |
| `list_keywords` | `client_id`, `limit`, `cursor` | Tracked keywords with volume, difficulty and intent. |
| `list_rankings` | `client_id`, `keyword`, `from`, `to` | Ranking history rows for charting or comparison. |
| `list_audits` | `client_id`, `limit` | Audit runs with score, issue counts and timestamps. |
| `get_audit_issues` | `client_id`, `audit_id` | Individual issues with severity, page and recommendation. |
| `list_backlinks` | `client_id`, `limit`, `cursor` | Referring domains with authority and first-seen date. |
| `list_citations` | `client_id` | Local directory listings and their accuracy status. |
| `list_articles` | `client_id`, `status` | Generated articles with status and deployment target. |
| `list_calls` | `client_id`, `from`, `to` | Tracked calls with source, transcript and lead grade. |
| `list_reports` | `client_id` | Generated client reports and share links. |

> **Discoverability**: The gateway ships a discovery endpoint listing every readable resource. The MCP server uses it at start-up, so new resources become available without a client update.

## Action tools

| Tool | Required inputs | Scope | Behaviour |
| --- | --- | --- | --- |
| `run_seo_audit` | `client_id`, `url` | `write` | Queues a crawl; returns an `audit_id` to poll. |
| `refresh_backlinks` | `client_id` | `write` | Refetches referring domains for the client. |
| `generate_keyword_ideas` | `client_id`, `seed` | `write` | Returns ideas with volume and difficulty. |
| `generate_topical_map` | `client_id`, `topic` | `write` | Builds a pillar-and-cluster content map. |
| `generate_article` | `client_id`, `keyword` | `write` | Drafts an article; returns an `article_id`. |
| `deploy_article` | `client_id`, `article_id` | `write` | Publishes to the connected site. Confirm first. |
| `optimize_page` | `client_id`, `url` | `write` | Returns on-page fixes for title, meta and headings. |
| `index_url` | `client_id`, `url` | `write` | Submits a URL for indexing. |
| `generate_press_release` | `client_id`, `topic` | `write` | Drafts a release for review. |
| `generate_gbp_post` | `client_id`, `topic` | `write` | Drafts a Google Business Profile post. |
| `run_local_grid_scan` | `client_id`, `keyword` | `write` | Runs a geo-grid rank scan around the location. |
| `analyze_llm_visibility` | `client_id` | `write` | Checks how assistants describe the brand. |
| `generate_outreach_email` | `client_id`, `prospect` | `write` | Drafts an outreach email. Does not send. |
| `send_prospect_email` | `client_id`, `email_id` | `write` | Sends a drafted email. Confirm first. |

## Shape of a tool call

**Tool input**

```json
{
  "name": "generate_article",
  "arguments": {
    "client_id": "c_8f21…",
    "keyword": "emergency dentist leeds",
    "word_count": 1400,
    "tone": "reassuring"
  }
}
```

**Gateway call**

```bash
curl -X POST "$AISOIQ_API_BASE" \
  -H "X-API-Key: $AISOIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "generate_blog",
    "client_id": "c_8f21…",
    "keyword": "emergency dentist leeds",
    "word_count": 1400
  }'
```

**Tool result**

```json
{
  "ok": true,
  "article_id": "a_5c09…",
  "status": "drafted",
  "title": "Emergency Dentist in Leeds: What To Do Tonight",
  "word_count": 1382
}
```

## Errors the assistant will see

| Status | Meaning | What the assistant should do |
| --- | --- | --- |
| 400 | Missing or invalid field | Ask you for the missing value; do not retry unchanged. |
| 401 | Bad or revoked key | Stop and report the auth failure. |
| 403 | Scope or client not permitted | Report the limit instead of trying another client. |
| 429 | Rate limited | Back off and retry with increasing delay. |
| 500 | Upstream job failure | Retry once, then report. |