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

# MCP Server

> Connect Claude, Cursor, and other MCP-compatible coding agents to DevTune AI search visibility data with the Streamable HTTP Model Context Protocol server.

DevTune exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so that AI agents can query your AI search visibility data directly. This lets agents like Codex, Claude, Cursor, and other MCP-compatible tools access your metrics and data directly.

## Server URL

The server uses **Streamable HTTP** transport at:

```text theme={null}
https://devtune.ai/api/mcp
```

The MCP server supports two setup paths:

* **OAuth** for interactive tools like Codex
* **API key** for non-interactive agents, CI jobs, or clients without OAuth support

## Setup

### Codex

Codex users can install the DevTune plugin from the DevTune plugin marketplace:

```bash theme={null}
codex plugin marketplace add devtunehq/codex-plugins --ref main
```

After adding the marketplace:

1. Restart Codex
2. Open the plugin list
3. Install the DevTune plugin
4. Sign in when Codex opens the browser authorization flow
5. Select the DevTune project the plugin should access

Once authorized, ask Codex to use DevTune for visibility summaries, citations, competitive positioning, actions, traffic, adoption metrics, or content gaps.

### Other OAuth MCP Clients

Use this configuration when your MCP client supports OAuth:

```json theme={null}
{
  "mcpServers": {
    "devtune": {
      "type": "streamable-http",
      "url": "https://devtune.ai/api/mcp"
    }
  }
}
```

When your client prompts for authorization, sign in to DevTune, select a project, and approve access.

### API Key

Use API keys for non-interactive agents, CI jobs, or clients without OAuth support. Pass your key in the `Authorization` header:

```text theme={null}
Authorization: Bearer dtk_live_your_key_here
```

#### Claude Desktop

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "devtune": {
      "type": "streamable-http",
      "url": "https://devtune.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

#### Cursor

Open **Settings > MCP Servers > Add Server**, or edit `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "devtune": {
      "type": "streamable-http",
      "url": "https://devtune.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

#### Claude Code

```bash theme={null}
claude mcp add devtune \
  --transport http \
  https://devtune.ai/api/mcp \
  --header "Authorization: Bearer dtk_live_YOUR_API_KEY_HERE"
```

## REST vs MCP

Use REST when you are building an app, job, warehouse sync, dashboard, or webhook consumer. Use MCP when an AI agent should inspect DevTune data and decide what to do next inside a workflow.

## Available Tools

| Category | Tool | Access | Description |
| - | - | - | - |
| Library | `devtune_list_library` | Read | List Library items, Current-only by default |
| Library | `devtune_search_library` | Read | Hybrid-search Library items, Current-only by default |
| Library | `devtune_read_library_item` | Read | Read content, provenance, version state, and agent availability |
| Library | `devtune_upload_library_item` | Write | Upload text as a Library item or the next version of an upload |
| Library | `devtune_update_library_item` | Write | Change agent availability or detach/relink a Superseded version |
| Knowledge | `devtune_get_knowledge_profile` | Read | Read the Knowledge Profile and Pending, Approved, and Dismissed proposals |
| Knowledge | `devtune_update_knowledge_profile` | Write | Apply an immediate human-authored edit to one Knowledge Profile field |
| Knowledge | `devtune_review_knowledge_proposal` | Write | Approve, dismiss, or restore a Knowledge Profile proposal |
| Overview | `devtune_get_visibility_summary` | Read | Share of voice, presence rate, brand awareness, and citation counts |
| Overview | `devtune_get_project_usage` | Read | Whether the project is paused, and its prompts, credits, AI Traffic events and tracked pages |
| Overview | `devtune_get_timeline_events` | Read | Prompt-set and tracked-URL changes, platform events, and detected citation-share changes that give context to trends |
| Diagnostics | `devtune_get_competitive_position` | Read | Competitive positioning time series (daily/weekly/monthly) |
| Diagnostics | `devtune_get_citation_analysis` | Read | Backward-compatible alias for top citation pages |
| Diagnostics | `devtune_get_top_citation_pages` | Read | Cursor-paginated top citation pages with URL, domain, classification, and position |
| Diagnostics | `devtune_get_top_citation_domains` | Read | Cursor-paginated top citation domains with counts, unique URLs, and class totals |
| Diagnostics | `devtune_get_citation_stats` | Read | Aggregate citation stats for the selected 30- or 90-day window |
| Recommendations | `devtune_get_actions` | Read | Suggested, accepted, live and archived actions, with matched-cohort citation defence on suggestions |
| Execution | `devtune_get_action_brief` | Read | Stored brief status and execution-ready markdown for an action DevTune suggested |
| Execution | `devtune_generate_action_brief` | Write | Queue or reuse brief generation for an action DevTune suggested; actions made with Create Action have no brief |
| Execution | `devtune_get_prompt_actions` | Read | Find existing and suggested actions whose stored evidence includes a prompt |
| Execution | `devtune_create_prompt_action` | Write | Create or reuse an action from a prompt, optionally generating a brief |
| Execution | `devtune_update_action` | Write | Rename an accepted or live action, set or clear its owner, change its channels, or edit its description (restore an archived action first) |
| Execution | `devtune_get_action_events` | Read | Who changed an action's title, owner, channels, description or published pages, newest first |
| Diagnostics | `devtune_get_traffic_summary` | Read | LLM bot and referral traffic analytics by site or path |
| Ground truth | `devtune_get_traffic_platforms` | Read | Traffic by AI platform over a fixed window, with verified and failed bot-identity verdict sums |
| Ground truth | `devtune_get_404_demand` | Read | Project-scoped classified 404 Demand and sensor coverage |
| Diagnostics | `devtune_get_adoption_metrics` | Read | npm downloads and GitHub stars trends |
| Recommendations | `devtune_get_content_gaps` | Read | Topic, source, and brand gaps you do not own, over a fixed rollup window |
| Ground truth | `devtune_get_page_metrics` | Read | Unified page metrics from the Audit rollup |
| Ground truth | `devtune_get_page_guard_rails` | Read | Paginated page guard-rail classifications |
| Ground truth | `devtune_list_attributes` | Read | Active and archived positioning statements |
| Ground truth | `devtune_get_attribute_match` | Read | Positioning match counts and share |
| Ground truth | `devtune_get_attribute_match_answers` | Read | The AI answers behind one positioning match cell |
| Ground truth | `devtune_get_accuracy` | Read | Claims AI answers made about your product, checked against your site, by outcome |
| Ground truth | `devtune_list_accuracy_claims` | Read | The contradicted, site-conflict, not-on-site or dismissed claims, most answers first |
| Ground truth | `devtune_get_accuracy_claim` | Read | One claim with its answers, pages, evidence and your team's decision |
| Ground truth | `devtune_list_accuracy_contradictions` | Read | Contradictions once per site sentence they conflict with, most answers first |
| Ground truth | `devtune_get_accuracy_contradiction` | Read | One site sentence with every AI wording that contradicts it |
| Ground truth | `devtune_list_accuracy_decisions` | Read | Your team's Accuracy decisions, newest first |
| Ground truth | `devtune_get_audit_summary` | Read | Completed Audit summaries, pillars, checks, and outcome trend |
| Ground truth | `devtune_get_audit_findings` | Read | Paginated Audit findings |
| Ground truth | `devtune_get_audit_extraction` | Read | Matching stored section, nearby Markdown and extraction timestamp |
| Ground truth | `devtune_get_google_eligibility` | Read | Fixed-window Google eligibility dimensions, transitions, and sitemap submission state |
| Ground truth | `devtune_get_outcomes_ledger` | Read | Results ledger and scoreboard |
| Ground truth | `devtune_attach_outcome_url` | Write | Attach a published URL and measure from the action completion date without waiting for a crawl |
| Ground truth | `devtune_get_ai_referrals` | Read | Complete paginated landing-page evidence, engine breakdown, and Traffic overview |
| Ground truth | `devtune_get_recent_answer_fetches` | Read | Up to 20 latest hourly answer-fetch records in the selected UTC window; requires `traffic.read` |
| Agents | `devtune_list_agents` | Read | Roster and custom-agent display fields |
| Agents | `devtune_list_agent_runs` | Read | Managed-agent run status, timing, usage, and identity |
| Agents | `devtune_get_agent_run` | Read | One run and its bounded draft artifact after completion |
| Agents | `devtune_run_agent` | Run | Trigger or reuse a metered manual run through the evidence- and credit-checked path |
| Agents | `devtune_list_dex_threads` | Read | Bounded recent Dex conversation threads and settled credits |
| Agents | `devtune_list_dex_handoffs` | Read | Pending specialist-agent handoffs for a Dex thread |
| Agents | `devtune_get_dex_events` | Read | Ordered, paginated Dex reply and lifecycle events |
| Agents | `devtune_start_dex_conversation` | Run | Start or idempotently reuse a metered Dex conversation |
| Agents | `devtune_send_dex_message` | Run | Steer an active Dex task or resume an expired thread |
| Agents | `devtune_rename_dex_thread` | Write | Rename a project-scoped Dex thread |
| Agents | `devtune_delete_dex_thread` | Write | Delete your private Dex chat after stopping live work; billing and audit records are retained |
| Agents | `devtune_decide_dex_handoff` | Run | Confirm or cancel a pending Dex specialist handoff |
| Agents | `devtune_decide_dex_memory` | Write | Save or dismiss a durable Dex memory offer |

Each windowed tool accepts only its documented fixed rolling windows and returns JSON data. Existing visibility tools use `30` and `90` days; the ground-truth tools mirror the application's `7`, `30`, and `90` day windows, with `365` also available for the Results ledger. Tool access depends on the project and permissions from your connection:

* OAuth connections use the project you selected during setup and your DevTune role
* API key connections use the project and permissions assigned to the key

When you approve an OAuth connection, DevTune saves the MCP capabilities you approved for the selected project. Read access includes Positioning, Accuracy, Pages, Audit, Results, Referrals, and Agents. Write tools and agent execution additionally require `devtune.manage`. Each request is limited to both the saved approval and your current permissions. Becoming a manager does not add write access to a connection you approved with read access only.

Connections approved before these capabilities were introduced keep their earlier access. They cannot use the added data tools or run agents until you explicitly approve the expanded access. Revoke the client's existing OAuth authorization and connect again to see the consent screen. A reconnect that skips consent does not add capabilities.

API-key connections require the corresponding tool scopes, including `agents.read` for managed-agent and Dex reads and `agents.run` for execution and Dex changes. Existing API keys do not receive new scopes automatically. Dex conversations remain private to their creator: OAuth uses the signed-in user, and API keys must be user-attributed. Account entitlements and credit requirements apply to both connection types.

High-stakes target pages require explicit customer acknowledgement through `acknowledgedHighStakes: true` before an action can be created. User-locked pages remain unavailable.

Creating an action from a prompt is free. Setting `generateBrief: true` reserves 2 content credits; the brief uses 1 to 2 credits depending on the research required. If generation cannot be queued, the action remains saved and the response returns `briefStatus: "failed"`. Open that action to retry. New content is drafted for human review and is never published by this operation.

Write-capable tools, including `devtune_create_prompt_action` and `devtune_generate_action_brief`, require permission to manage actions for the selected project.

`devtune_update_action` renames an action, sets its owner, changes its channels, or edits its description. It works on accepted and live actions; restore an archived action first. DevTune's suggestions, including dismissed and snoozed ones, keep their details and have no owner. `assignedTo` takes a member's user id or the email they sign in with, and must name a current member of the account. `channels` is the full set of channels that own the work (at least one); it replaces the current set, and order does not matter. `description` changes only on an accepted action your team created: DevTune's actions keep the description their evidence wrote, and a live action's description is fixed until you reopen it. `devtune_get_actions` returns each action's `assignedTo` and `ownerName`.

`devtune_get_action_events` lists who changed an action's title, owner, channels, description or published pages, newest first: one event per changed field, and one per published page added or removed. Each event has a `kind`, `from` and `to` values (owners as user ids, channels as arrays, pages as URLs), an `actor` and `createdAt`. The actor is a `user` with their id and name while they are still a member, an `api_key` with its key id, or `system` for edits DevTune makes. Accepting, going live and archiving are not events; read them from `devtune_get_actions`. History starts when DevTune began recording edits, so earlier changes are not listed.

## Library and Knowledge permissions

Library and Knowledge tools use two explicit scopes:

* `library.read` allows `devtune_list_library`, `devtune_search_library`, `devtune_read_library_item`, and `devtune_get_knowledge_profile`.
* `library.write` allows `devtune_upload_library_item`, `devtune_update_library_item`, `devtune_update_knowledge_profile`, and `devtune_review_knowledge_proposal`.

`library.write` is a mutation grant. It permits the MCP client to upload project text, change whether a Library item is available to agents, detach or relink Superseded versions, directly edit the Knowledge Profile, and approve, dismiss, or restore profile proposals. A direct edit and an approval both change the target profile field; dismissing or restoring a proposal does not.

Use `devtune_update_knowledge_profile` only for a deliberate human-authored edit. It applies immediately. System observations and agent learnings must remain proposals for review.

API-key connections need the matching scopes on the key. Existing keys do not receive `library.read` or `library.write` automatically. OAuth connections include Library scopes for the selected project, but write tools still require the signed-in user to have project management permission.

Library list and search tools return Current versions by default. Set `includeSuperseded: true` for deliberate historical retrieval. Results expose version state and numbering; a specific older item can be read by ID without being presented as current. Turning agent availability off does not hide an item from these UI, REST, or MCP reads. It prevents the item from being retrieved into managed-agent prompts.

`devtune_get_ai_referrals` returns the same coverage as the REST Referrals endpoint in `overview.referralCoverage`: `sessionsCurrent`, `sessionsPrevious`, `conversionsCurrent`, and `conversionsPrevious`. Known counts remain visible when coverage is partial. Compare a metric across periods only when both of its flags are true, including engine and landing-page comparisons.

`devtune_get_content_gaps` maps to `GET /api/v2/projects/{projectId}/content-gaps/list`. It returns the same measured topic, source, and brand rollup facts, coverage state, and offset/limit pagination as REST. Your own sources and brand are excluded, as are topics you hold at least half the citations on, because those are presence rather than a gap. Every count is a citation split into primary and competitor; the rollups hold no mention facts. Coverage reports `availableDays`, `isPartial`, and the `asOfDate` the window ends on, so a window that was rolled up from fewer days than requested says so. Use `gapType` or display-label `search` to narrow the list. Actions remain the source for workflow state, briefs, and interventions.

## Tool Inputs

| Tool | Inputs |
| - | - |
| `devtune_get_project_usage` | No inputs. Available to every key and MCP connection. Returns the same document as `GET /projects/{projectId}/usage`: `paused`, active prompts, credits spent this credit period, AI Traffic events this UTC month and tracked pages against the page limit, each with its own period, plus `deletion` dates when the project or its team account is scheduled for [inactive data deletion](/account-billing/inactive-data-deletion). A paused project gives credentials read access only until it is resumed in the app. |
| `devtune_list_attributes` | No inputs. Requires `attributes.read`. |
| `devtune_get_attribute_match` | `window` (`30` or `90`, default `30`), optional `platform` and `intent`. Requires `attributes.read`. Returns the same positioning match document as the REST endpoint, including null shares below ten named-product assignments and each statement's comparison with the previous window. |
| `devtune_get_attribute_match_answers` | `attributeId`, `assignee` (a brand id, or `another_product`, `several` or `nobody`), `window` (`30` or `90`, default `30`), optional `platform`, `intent`, `cursor`, and `limit` (`1`-`100`, default `25`). Requires `attributes.read`. Lists the answers one match cell counts, newest first; pass `nextCursor` verbatim with the other inputs unchanged. |
| `devtune_get_accuracy` | `window` (`30` or `90`, default `30`), optional `platform` and `intent`. Requires `accuracy.read`. Returns the same Accuracy document as the REST endpoint: claims by outcome and the match rate, the previous window when `prior_status` is `comparable`, the weekly trend, the per-platform split and check coverage. When `facts` is zero, read `coverage`: pending answers have not been checked yet. |
| `devtune_list_accuracy_claims` | `outcome` (`contradict`, `site_conflict`, `not_on_site` or `dismissed`), `window` (`30` or `90`, default `30`), optional `platform`, `intent`, `cursor`, and `limit` (`1`-`100`, default `25`). Requires `accuracy.read`. Lists claims with that outcome, most answers first; pass `next_cursor` verbatim with the other inputs unchanged. An empty list means no claim had that outcome in the window. |
| `devtune_get_accuracy_claim` | `groupId` (a `group_id` from `devtune_list_accuracy_claims`), `window` (`30` or `90`, default `30`), optional `platform` and `intent`. Requires `accuracy.read`. `outcome` and `claim` are null when the claim made no answer in the window and filters. |
| `devtune_list_accuracy_contradictions` | `window` (`30` or `90`, default `30`), optional `platform`, `intent`, `cursor`, and `limit` (`1`-`100`, default `25`). Requires `accuracy.read`. Lists one row per site sentence that contradictions conflict with, most answers first, with how many AI wordings contradict it and how many were dismissed; a row whose wordings were all dismissed is not listed. Pass `next_cursor` verbatim with the other inputs unchanged. |
| `devtune_get_accuracy_contradiction` | `sentenceKey` (a `sentence_key` from `devtune_list_accuracy_contradictions`, or from a contradiction in `devtune_list_accuracy_claims`), `window` (`30` or `90`, default `30`), optional `platform` and `intent`. Requires `accuracy.read`. `wordings` is empty when the row has none in the window and filters. |
| `devtune_list_accuracy_decisions` | optional `cursor` and `limit` (`1`-`100`, default `25`). Requires `accuracy.read`. Lists active and undone decisions, newest first. An empty list means no claim has been reviewed. |
| `devtune_list_library` | optional `cursor`, optional `includeSuperseded`, optional `limit` (`1`-`100`, defaults to `25`) |
| `devtune_search_library` | `query`, optional `cursor`, optional `includeSuperseded`, optional `limit` (`1`-`100`, defaults to `25`) |
| `devtune_read_library_item` | `itemId` |
| `devtune_upload_library_item` | `title`, `content` (up to 500,000 characters), optional `replaceItemId` |
| `devtune_update_library_item` | `itemId`, optional `groundingEnabled`, optional `successorId` (UUID to relink; `null` to detach) |
| `devtune_get_knowledge_profile` | optional `cursor`, optional `limit` (`1`-`100`, defaults to `25`) |
| `devtune_update_knowledge_profile` | `targetField` (`company_context`, `tone`, `saved_instructions`), `value` (up to 12,000 characters) |
| `devtune_review_knowledge_proposal` | `proposalId`, `decision` (`approve`, `dismiss`, `restore`) |
| `devtune_get_visibility_summary` | `windowDays` (`30`, `90`), optional `platform`, optional `topicId` |
| `devtune_get_timeline_events` | `windowDays` (`30`, `90`); requires `visibility.read` |
| `devtune_get_competitive_position` | `windowDays` (`30`, `90`), optional `platform`, optional `topicId`, optional `grouping` (`daily`, `weekly`, `monthly`) |
| `devtune_get_citation_analysis` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` |
| `devtune_get_top_citation_pages` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search`, optional `sourceVertical` |
| `devtune_get_top_citation_domains` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search`, optional `sourceVertical` |
| `devtune_get_citation_stats` | `windowDays` (`30`, `90`) |
| `devtune_get_actions` | optional `status`, optional `priority`, optional `channel`, optional `detailLevel` (`summary`, `context`), optional `page`, optional `pageSize` |
| `devtune_get_action_brief` | `actionId` |
| `devtune_generate_action_brief` | `actionId`, optional `briefStyle` |
| `devtune_get_prompt_actions` | `promptId` |
| `devtune_create_prompt_action` | `promptId`, `title`, `description`, optional `targetUrl`, optional `generateBrief` (defaults to `false`), optional `acknowledgedHighStakes` |
| `devtune_update_action` | `actionId`, optional `title`, optional `assignedTo` (a member's user id or sign-in email, or `null` to unassign), optional `description`, optional `channels` (an array of `docs`, `content`, `devrel`, `pr`, `engineering`, `product` or `other`) |
| `devtune_get_action_events` | `actionId`, optional `pageSize` (`1`-`100`, defaults to `25`), optional `cursor` |
| `devtune_get_traffic_summary` | `windowDays` (`30`, `90`), optional `domain`, optional `pathPrefix` with `domain` |
| `devtune_get_traffic_platforms` | `windowDays` (`30`, `90`), optional `domain` |
| `devtune_get_404_demand` | none |
| `devtune_get_adoption_metrics` | `windowDays` (`30`, `90`), optional `metric` (`github_stars`, `weekly_downloads`) |
| `devtune_get_content_gaps` | `windowDays` (`30`, `90`), optional `gapType` (`topic`, `source`, `brand`), optional `search`, optional `offset`, optional `limit` (`1`-`100`) |
| `devtune_get_page_metrics` | `windowDays` (`7`, `30`, `90`), optional `cursor`, `pageSize`, `category`, `sortKey`, `sortDirection` |
| `devtune_get_page_guard_rails` | optional `offset`, optional `pageSize` |
| `devtune_get_audit_summary` | `windowDays` (`7`, `30`, `90`) |
| `devtune_get_audit_findings` | optional `includeDismissed`, optional `offset`, optional `pageSize` |
| `devtune_get_audit_extraction` | `domain`, `pagePath`, `contentHash`, `inputHash`, `locator` from a section finding. Requires `audit.read`. |
| `devtune_get_google_eligibility` | optional `windowDays` (`7`, `30`, `90`), optional `evidenceLimit` (`1`-`25`, defaults to `10`); unavailable projects return `Resource not found` |
| `devtune_get_outcomes_ledger` | `windowDays` (`7`, `30`, `90`, `365`), optional `cursor`, `pageSize`, `status`, `interventionId` |
| `devtune_get_ai_referrals` | `windowDays` (`7`, `30`, `90`), optional `cursor`, optional `pageSize` |
| `devtune_list_agents` | none |
| `devtune_list_agent_runs` | optional `agentKey`, optional `cursor`, optional `pageSize` |
| `devtune_get_agent_run` | `runId` |
| `devtune_run_agent` | `agentKey`, `requestIdempotencyKey`, optional `instructions`, optional `modelId` |

For `devtune_get_outcomes_ledger`, supply `interventionId` to include 7-, 14-, 30-, and 90-day impact windows for a completion-based measurement: citations and presence, plus answer fetches per sensor-covered day with their own `answerFetchEvidenceQuality`. Unfinished or unsupported comparisons return null deltas. The main outcome still uses its 14-day comparison.

For `devtune_get_actions`, the most useful filters are:

* `detailLevel`: `summary` or `context`; `summary` is default
* `status`: `suggested` (DevTune proposed it and nobody has decided), `accepted` (the team wants it done), `live` (the change is published; its measurement is running or complete) or `archived` (off the queue); omit it to get every status. Blocked work is an accepted action with `blocked: true`, not a separate status.
* `priority` and `channel` for narrower work queues

Use `detailLevel: "context"` when the agent needs to understand why an action matters before deciding what to do. Context responses are capped to keep tools fast and predictable: up to 3 evidence blocks and 5 citation/source references per action, plus scores, metrics, brief readiness, and follow-up links. Guard-rail evidence includes `googleEligibility` only when the caller is entitled and the evidence has a fresh observation from a live exact-domain GSC source. It includes `canonical`, `crawlable`, `indexed`, and `structuredData` states (`pass`, `fail`, or `unmeasured`), together with `observedAt` and Google's `coverageState`.

Citation-defence opportunities in `devtune_get_actions` use successful executions for prompt/platform cells present in both 30-day windows. Their measurements include the matched execution totals, the cohort's coverage of earlier citations, informational probe-day counts, and prompts or platforms present in only one window. DevTune withholds the loss claim when the matched cohort covers less than 60% of the earlier citation volume.

For visibility, citation, content-gap, traffic-summary, adoption, and intelligence tools, `windowDays` accepts `30` or `90` and defaults to `30`. Ground-truth tools accept the windows shown above and default to `30`. Citation top-list tools use cursor pagination and support simple prefix search on URL and domain. Content gaps use `offset` and `limit` pagination and support display-label search. `devtune_get_citation_stats` returns aggregate totals only and does not accept pagination or search inputs. Unsupported arbitrary ranges and undocumented filters are rejected instead of being handled downstream.

## Which Tool Should I Use?

| Goal | Tool |
| - | - |
| Browse the current Library catalog | `devtune_list_library` |
| Find relevant current or older material | `devtune_search_library`, then `devtune_read_library_item` |
| Add project text to the Library | `devtune_upload_library_item` |
| Control grounding or version links | `devtune_update_library_item` |
| Read company context and proposals | `devtune_get_knowledge_profile` |
| Apply a deliberate profile edit | `devtune_update_knowledge_profile` |
| Review a profile proposal | `devtune_review_knowledge_proposal` |
| See the account/project health snapshot | `devtune_get_visibility_summary` |
| Explain a change in a Visibility trend | `devtune_get_timeline_events` |
| Diagnose citation/source movement | `devtune_get_top_citation_pages`, `devtune_get_top_citation_domains`, or `devtune_get_citation_stats` |
| See which communities AI cites | `devtune_get_top_citation_domains` with `sourceVertical: "community"` |
| Compare primary brand vs competitors | `devtune_get_competitive_position` |
| Check what AI says against your site | `devtune_get_accuracy`, then `devtune_list_accuracy_contradictions` and `devtune_list_accuracy_claims` |
| Find recommended work | `devtune_get_actions` |
| Understand why a recommendation matters | `devtune_get_actions` with `detailLevel: "context"` |
| Execute a recommendation | `devtune_get_action_brief` or `devtune_generate_action_brief` |
| Diagnose page-level ground truth | `devtune_get_page_metrics`, `devtune_get_page_guard_rails` |
| Review Audit findings and trends | `devtune_get_audit_summary`, `devtune_get_audit_findings`, `devtune_get_audit_extraction` |
| Review Google eligibility | `devtune_get_google_eligibility` |
| Connect work to measured outcomes | `devtune_get_outcomes_ledger` |
| Inspect AI-referral demand | `devtune_get_ai_referrals` |
| Inspect conversion events by AI engine | `devtune_get_ai_referrals` |
| Inspect missing-page demand | `devtune_get_404_demand` |
| Review agent availability and runs | `devtune_list_agents`, `devtune_list_agent_runs`, `devtune_get_agent_run` |
| Trigger an idempotent agent run | `devtune_run_agent` |

### Triggering a Managed-Agent Run

`devtune_run_agent` requires `agents.run` on an API key or `devtune.manage` for an OAuth connection, and a caller-generated UUID in `requestIdempotencyKey`. Retrying with the same key reuses the existing run. The tool delegates to the same evidence- and credit-checked dispatch path as the application, including evidence preflight, model-catalog validation, autonomy rules, and credit reservation and settlement. It creates no external draft-write capability; completed draft artifacts are read with `devtune_get_agent_run` and approval remains in the application.

### Generating Action Briefs

`devtune_generate_action_brief` is the MCP write operation for briefs in the Actions queue. It takes the following inputs:

| Parameter | Type | Description |
| - | - | - |
| `actionId` | string | UUID of the action to generate a brief for |
| `briefStyle` | string | Optional style override. Use `best_fit` or an allowed content format such as `technical_guide`. |

When project content preferences are enabled, `briefStyle` must respect the project's allowed and blocked formats. Requests for blocked formats are rejected instead of silently generating the blocked style.

The tool is idempotent for a ready or already-running brief:

* If the brief is ready, it returns `status: "ready"`
* If generation is already running, it returns `status: "generating"`
* If generation can start, it queues background work and returns `status: "queued"`

The response includes `success`, `message`, `actionId`, and, when queued, an `eventId`. Use `devtune_get_action_brief` afterward to poll for readiness and retrieve the generated markdown.

## Example Prompts

Once connected, you can ask your AI agent questions like:

* "What is my current share of voice across AI platforms?"
* "Show me the competitive position trend for the last 30 days"
* "Show my top citation pages and domains for the last 90 days"
* "Summarize my aggregate citation stats for the last 30 days"
* "List suggested actions for this project"
* "Load the stored brief for action 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab and summarize the execution plan"
* "Generate the action brief for action 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab"
* "Show accepted actions that are blocked"
* "Which content-gap topics, sources, and brands are cited most this month, and how much of that is mine?"
* "Show page-level blind spots and guard rails for the last 30 days"
* "Summarize open Audit findings and measured results for this project"
* "List available agents and their recent runs"
* "Run the Technical Auditor with idempotency key 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab"
* "How much traffic am I getting from AI chatbots?"
* "Search the current Library for our positioning guidance, then show the version and as-of date."
* "List Pending Knowledge Profile proposals and explain their provenance."

## Related Documentation

* [**Authentication**](/api-reference/authentication) — API key and MCP OAuth authentication
* [**Rate Limits**](/api-reference/rate-limits) — Request limits by plan tier
* [**API Overview**](/api-reference/overview) — Full list of REST API endpoints

## Prompt-set analysis

Use the [prompt-set analysis workflow](/search-tracking/prompt-set-analysis) to read assessments, proposals and credit state, start approved analyses, and apply, undo, dismiss or restore approved proposals. Reads never charge credits or mutate prompts. Interactive review is available in-app; Slack execution is unsupported.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.