# Tools

The full set of tools the Orchly MCP exposes: 36 in total, 26 read-only and 10 that change your setup. Your assistant picks the right ones; this is the reference for what's available.

Tools are grouped by intent, the same four tiers as the [REST API](/content/help/api/index.html). Read tools carry a
read-only hint, so clients run them without asking. Write tools are marked **Write** below and your
client confirms before each one runs.

Read pulls data, no changes.
Write changes your workspace, needs confirmation.

## Discover

Get the IDs you need to make every other call.

| Tool                  | Access | What it does                                                   | Key arguments            |
|-----------------------|--------|---------------------------------------------------------------|--------------------------|
| `list_workspaces`     | Read   | List the workspaces this key can target.                     | none                     |
| `get_usage`           | Read   | This organization's API usage versus its plan limit.          | none                     |
| `list_models`         | Read   | List tracked AI engines/models usable as the platform filter. | none                     |
| `list_platforms`      | Read   | List tracked answer-engine platform IDs.                      | none                     |
| `list_topics`         | Read   | List topics (the grouping for prompts) in the workspace.     | `workspace_id`          |
| `list_brands`         | Read   | List tracked brands (own + competitors) in the workspace.    | `workspace_id`          |

## Analyze

The analytical read surface.

| Tool                          | Access | What it does                                                   | Key arguments                      |
|-------------------------------|--------|---------------------------------------------------------------|------------------------------------|
| `get_visibility_kpis`        | Read   | AI-visibility headline KPIs for a brand over a date range.   | `workspace_id, brand_id?, dates, filters` |
| `get_visibility_timeseries`   | Read   | AI-visibility and execution trend over time.                  | `workspace_id, dates, filters`            |
| `get_visibility_leaderboard`  | Read   | Top brands by AI visibility.                                   | `workspace_id, dates, filters`            |
| `compare_brands`             | Read   | Multi-brand comparison matrix.                                 | `workspace_id, brand_ids?`         |
| `get_visibility_breakdowns`   | Read   | Visibility broken down by platform or topic.                  | `workspace_id, by`                    |
| `list_mentions`              | Read   | Recent brand mentions across AI answers.                       | `workspace_id, dates, filters`      |
| `list_executions`            | Read   | Prompt executions (the LLM runs behind the analytics).        | `workspace_id, prompt_id?`          |
| `get_citations`              | Read   | Citation analytics. view: sources \| domains \| timeseries. | `workspace_id, view`                |
| `get_sentiment`              | Read   | Sentiment analytics. view: summary \| themes \| timeseries. | `workspace_id, view`                |
| `get_fanouts`                | Read   | Top query fan-outs (expanded queries).                         | `workspace_id, dates`               |
| `get_shopping`               | Read   | Shopping visibility (Pro+). view: visibility \| products \| merchants. | `workspace_id, view`                |
| `get_ai_traffic`            | Read   | AI/bot referral traffic (Pro+). view: kpis \| timeseries \| breakdowns. | `workspace_id, view`                |
| `get_gsc`                   | Read   | Google Search Console organic. view: kpis \| timeseries \| dimension. | `workspace_id, view`          |
| `get_ranks`                  | Read   | Tracked rank-tracker keywords for the workspace.              | `workspace_id, limit?`              |
| `get_site_health`            | Read   | Tracked pages (Page360) with their latest audit score.       | `workspace_id, limit?`              |

## Configure

Manage the inputs you track. Write tools; your client confirms first.

| Tool                        | Access | What it does                                                   | Key arguments                     |
|-----------------------------|--------|---------------------------------------------------------------|-----------------------------------|
| `add_prompt`                 | Write  | Track a new AI-visibility prompt under a topic.              | `workspace_id, topic_id, prompt_text`  |
| `set_prompt_active`         | Write  | Enable or disable tracked prompts.                             | `workspace_id, prompt_ids, active` |
| `create_topic`               | Write  | Create a topic to group prompts.                              | `workspace_id, name`               |
| `add_keyword`                | Write  | Add a keyword to the rank tracker.                            | `workspace_id, keyword`             |
| `track_competitor`          | Write  | Start tracking a competitor brand.                             | `workspace_id, canonical_name, primary_domain?` |

## Act

Trigger and track work.

| Tool                       | Access | What it does                                                   | Key arguments                     |
|----------------------------|--------|---------------------------------------------------------------|-----------------------------------|
| `list_recommendations`      | Read   | Planner-generated opportunities (recommendation tasks).      | `workspace_id, status?`          |
| `list_tasks`               | Read   | List Mission Control tasks.                                   | `workspace_id, status?, type?`    |
| `create_task`              | Write  | Create a Mission Control task (origin=api).                 | `workspace_id, type, title`       |
| `run_task`                 | Write  | Trigger the agent run for a task (async).                   | `workspace_id, task_id`           |
| `get_run`                  | Read   | Poll an agent run status and result.                         | `workspace_id, run_id`            |
| `approve_run`              | Write  | Approve or reject a run paused at the autonomy gate.        | `workspace_id, run_id, action`    |
| `list_documents`           | Read   | List agent-authored documents.                               | `workspace_id, status?`           |
| `get_document`             | Read   | Read one document by ID.                                     | `workspace_id, document_id`       |
| `create_document`          | Write  | Create a markdown document.                                   | `workspace_id, title, content_markdown?` |
| `update_document`          | Write  | Update a document (title, markdown, or status).             | `workspace_id, document_id`       |

## Notes

- **Workspace scope.** Most tools take a `workspace_id`. Ask the assistant to list workspaces first if you're not sure which to use.
- **Async work.** `run_task` starts an agent run and returns immediately. Poll `get_run` for status and the result.
- **Plan gating.** Shopping and AI-traffic tools need a Pro plan or higher, the same as the dashboard.
- **Same permissions as the API.** Every call respects your key's scopes, so the MCP can never do more than your [API key](/content/help/api/index.html) allows.