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

# Tool reference

> Every tool the SeoSorted MCP server exposes, what it costs and what it returns.

Twelve tools, grouped by what they are for. Each one is a job you would actually ask for —
not a wrapper around an API endpoint — so an agent can go from *"write me something about X"*
to a finished draft without you naming the steps.

## Context

### `get_site_profile`

Your website, business context, brand voice, blog settings, connected integrations, plan and
remaining credits. Free and instant.

Worth calling first in any conversation: it tells the agent what the rest of the tools can do
in this workspace, so it stops guessing.

## Research

### `list_keywords`

Browse the keywords you already track. Filter by `status`, `search`, `flagged`, `limit`.

Free. Returns a table plus a suggestion — typically which term is the best next article.

### `research_keywords`

Look up live volume, difficulty, CPC and intent for new terms and save them to your workspace.

**Costs one keyword-lookup credit.** Pass `enrich: false` to save terms without spending one.

## Site health

### `run_site_audit`

Crawls your site and scores it across technical, content, schema, backlinks and analytics.

**Costs one audit credit.** Takes several minutes, so it returns a job id immediately — the
agent then calls `wait_for_job`.

### `get_audit`

Reads a finished audit. Returns scores and issue **counts** grouped by severity and category
rather than every issue, so a large audit does not flood the conversation:

```
Audit cmshciep3000euro1lwdarp5q · 4 pages crawled

Overall 90 · technical 100 · content 98 · schema 95 · analytics 50

3 issues — CRITICAL 1 · WARNING 2

- CONTENT: 1
- SCHEMA: 1
- LINKS: 1
```

Pass `severity` or `category` to drill into the specific issues behind a count. Defaults to
your most recent audit.

## Content

### `list_articles`

Browse articles with status, word count and keyword. Metadata only.

### `get_article`

Reads one article. The `include` parameter controls how much comes back:

| `include`          | Returns                                               |
| ------------------ | ----------------------------------------------------- |
| `meta` *(default)* | Title, status, word count, meta title and description |
| `outline`          | Adds the heading structure                            |
| `full`             | The entire body                                       |

Default to `meta`. A 2,000-word body is a lot of conversation to spend when the question was
"is it published yet".

### `generate_article`

Runs the full writing pipeline for a keyword: SERP research, competitor analysis, outline,
draft, humanise, internal links, images and metadata.

**Costs one article credit** and takes roughly three minutes. Returns a job id immediately.

Pass `keywordId` to write something new, or `articleId` to regenerate an existing draft.

<Tip>
  The response tells the agent how many credits are left **including generations still running**,
  so it does not start four articles believing it has four credits.
</Tip>

## Publishing

### `list_integrations`

Your connected CMS and analytics destinations, with status. Call it to get a valid
`integrationId`.

**Pro feature.**

### `publish_article`

Publishes an article to a connected CMS.

**Pro feature. Writes to your live website.** Two safeguards:

* `dryRun: true` returns the exact article, destination, slug and metadata that would be sent,
  and publishes nothing.
* `confirm: true` is required to publish for real. Without it the tool refuses and tells the
  agent to show you what will happen first.

It also needs the `publish` scope, which is **not** granted by default — a key without it
cannot publish no matter what plan you are on.

## Jobs

Audits, article generation and publishing all run in the background.

### `check_job`

Returns status and the current step immediately:

```
Job cmsqcrmty000furpl9bly014v (generate-article) is ACTIVE — Writing content
```

### `wait_for_job`

Blocks until the job finishes, up to `timeoutSeconds` (default 60, max 240). If it is still
running when the timeout hits, it returns the latest progress step and tells the agent to call
again. Better than polling `check_job` in a loop.

## Cost at a glance

| Tool                                                                                                          | Credit         | Plan                  |
| ------------------------------------------------------------------------------------------------------------- | -------------- | --------------------- |
| `get_site_profile`, `list_keywords`, `list_articles`, `get_article`, `get_audit`, `check_job`, `wait_for_job` | —              | Any                   |
| `research_keywords`                                                                                           | Keyword lookup | Any                   |
| `run_site_audit`                                                                                              | Audit          | Any                   |
| `generate_article`                                                                                            | Article        | Any                   |
| `list_integrations`                                                                                           | —              | Pro                   |
| `publish_article`                                                                                             | —              | Pro + `publish` scope |

See [Plans, credits and limits](/mcp/limits) for the allowances behind each credit.