KnitKnot
You are reading the agent-optimized layer of this page: the literal markdown we serve to AI crawlers and assistants, shipped in the page source of every visit. Making sure AI reads the right facts about a company is literally what KnitKnot does.

# MCP tools reference

Every customer-facing tool in the KnitKnot MCP server: what each does, its parameters, and what it returns, so you or your AI assistant know exactly which tool to call.

The authenticated KnitKnot MCP server exposes your authorized workspace to AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io/). Connecting is covered in [Connect to your AI tools](/docs/connect-to-ai-tools/). This server is separate from the read-only `/mcp` interface that is rolling out on managed customer domains.

The surface is deliberately lean and REST-style: `list_*` returns a paginated index (scalars only), a matching `get_*` drills into one entity, and there is one write tool to act. Coverage matrices, the topic ontology, and the question library are console concerns; their conclusions are distilled into ranked `list_issues` (diagnose) and `list_playbooks` (fix) responses. Paginated responses carry `pagination: {has_more, offset}`; page by passing `offset`. Every call returns JSON scoped to **your** workspace, and a status change made via an assistant appears in the console.

## Orient

### `get_workspace_context`

Company, subjects (brands + products), competitors, capabilities, buyer roles, and topics. Call first to orient the assistant before a task. No parameters.

## How am I doing, and who's the threat?

### `competitive_overview`

Your AI Presence Score, W/L per competitor (sorted by threat), per-engine performance, top capability gaps, headline metrics (visibility, share of voice, average rank, sentiment), and brand coherence. A current snapshot that enumerates competitors, so it subsumes a separate competitor list.

**Params:** `subject_name` *(opt)* : product/brand name to scope to; omit for workspace-wide.

### `get_competitor`

One competitor deep dive: research profile (capabilities, positioning, differentiators), head-to-head W/L, per-engine W/L/T, per-capability W/L, top cited sources.

**Params:** `competitor_name` *(req)* : name from `competitive_overview`.

## Diagnose → prove → fix → act

### `list_issues`

The workspace's Issues : the ranked diagnostic catalog of what AI gets wrong about you or where you're losing, most-important-first. Each carries an `importance_score` (0-100). Light index; call `get_issue` for the proof, action, and linked playbooks.

**Params:** `status` *(opt)* `candidate`|`open`; `issue_type` *(opt)* `misrepresentation`|`feature_gap`|`visibility_gap`|`source_gap`; `subject_name` *(opt)*; `limit` *(opt, default 20, max 50)*; `offset` *(opt)*.

### `get_issue`

One issue's verbatim proof + what to do.

  • - **Answer-grain** (visibility/competitor gaps): the backing answers : each row's `evaluation_id`, `prompt_text` (the buyer question), `engine`, `outcome`, `coverage`. Pass an `evaluation_id` to `read_evaluation` for the full AI answer.
  • - **Claim-grain** (misrepresentation, source leak, negative sentiment, capability loss): the exact claims AI made : `verbatim_quote`, verdict, severity, engine, source URL. The API retains its established feature-oriented enum values.
  • - Plus `recommended_action`, `fixability` (grounded = editable page vs parametric = baked into the model), and `linked_playbooks`.

Want the questions that **track** a fix? Each `linked_playbook` has an `id` : pass it to `get_playbook` with `include=["questions"]` for its `tracked_prompts` (worst first).

**Params:** `issue_id` *(req)* : from `list_issues`.

### `read_evaluation` (read an Answer)

The full AI answer behind one scored Answer: the raw `response_text` plus the judge's extraction : `score`, `competitive_outcome`, `positioning_accuracy`, `sentiment`, capabilities mentioned/missing, `recommendation`. The API keeps its established `read_evaluation`, `evaluation_id`, and `tracked_prompts` field names even though the console labels these objects Answers and Questions.

Id-anchored only (no free-form workspace search) so the agent stays on the diagnose → prove → fix path. Responses >6,000 chars are truncated (`truncated: true`, `response_length` total) : hand the id to your client's fetch tool for the unabridged text.

**Params:** `evaluation_id` *(req)* : from `get_issue`'s `example_evaluations` or `get_playbook`'s `tracked_prompts`.

### `list_playbooks`

The Playbooks : the fixes for your issues : ranked highest-ROI-first. Defaults to active work (`proposed`, `in_progress`). Each carries its ramp `phase` (`fix-now`, `create-for-coverage`, `deepen`, `earn`) and `phase_label`. The response top level carries the workspace's ramp `stage` (`estimated: true` when computed on partial data : treat the roadmap as provisional) and a `generating_count` of playbooks still being drafted.

**Params:** `statuses` *(opt, default `["proposed","in_progress"]`)* : pass `["shipped"]` to see shipped (`dismissed` is internal-only); `playbook_types` *(opt)* `comparison_page`|`feature_page`|`correction`|`third_party`|`refresh`|`icp_content`; `limit` *(opt, default 20, max 50)*; `offset` *(opt)*.

### `get_playbook`

Everything needed to **draft** the content for one playbook : most importantly the exact buyer keywords and terms to write with. Sections selected by `include`; omit it for the full drafting payload (keywords, brief, page-to-beat, critique, receipts).

The `questions` section is the questions the play is measured against (`tracked_prompts`, worst first) : opt in with `include=["questions"]`. This is how an agent finds the questions linked to an issue once it lands on the play that addresses it, and where the `evaluation_id`s for `read_evaluation` also live.

**Params:** `playbook_id` *(req)* : from `list_playbooks` or a `linked_playbook.id`; `include` *(opt)* : subset of `keywords`, `brief`, `page_to_beat`, `critique`, `receipts`, `questions`. Omit for the full set excluding `questions`; pass a narrow subset to fetch one slice fast.

### `update_playbook_status`

Update a playbook's status : the one write tool. Changes appear in the console.

**Params:** `playbook_id` *(req)*; `new_status` *(req)* `in_progress`|`shipped`|`dismissed`; `shipped_url` *(req when shipping content plays)* : URL where content was published (earn-verb plays ship as "outreach sent" with no URL; an optional evidence link is stored but never treated as an owned page); `dismissed_reason` *(req when dismissing)* : `ignored`, or a granular `irrelevant`|`wrong_evidence`|`already_done`|`bad_target`|`too_much_effort`|`other`.

That's the full set. Internal (superadmin-only) tools : coverage matrices, the topic ontology, the question library listing, score-trend history, and more : are hidden from customer callers by the curation allowlist and not listed here. One can be promoted to the customer surface deliberately when a real agent workflow emerges for it.

Next: how gaps become [issues and playbooks](/docs/issues-and-playbooks/), or back to [connecting your AI tools](/docs/connect-to-ai-tools/).

Raw mirror of this content: https://knitknot.ai/docs/mcp-tools.md. Site-wide summary: /llms.txt · full content: /llms-full.txt

Docs navigation
Docs › Reference

MCP tools reference

Every customer-facing tool in the KnitKnot MCP server: what each does, its parameters, and what it returns, so you or your AI assistant know exactly which tool to call.

Updated

The authenticated KnitKnot MCP server exposes your authorized workspace to AI assistants via the Model Context Protocol. Connecting is covered in Connect to your AI tools. This server is separate from the read-only /mcp interface that is rolling out on managed customer domains.

The surface is deliberately lean and REST-style: list_* returns a paginated index (scalars only), a matching get_* drills into one entity, and there is one write tool to act. Coverage matrices, the topic ontology, and the question library are console concerns; their conclusions are distilled into ranked list_issues (diagnose) and list_playbooks (fix) responses. Paginated responses carry pagination: {has_more, offset}; page by passing offset. Every call returns JSON scoped to your workspace, and a status change made via an assistant appears in the console.

Orient

get_workspace_context

Company, subjects (brands + products), competitors, capabilities, buyer roles, and topics. Call first to orient the assistant before a task. No parameters.

How am I doing, and who’s the threat?

competitive_overview

Your AI Presence Score, W/L per competitor (sorted by threat), per-engine performance, top capability gaps, headline metrics (visibility, share of voice, average rank, sentiment), and brand coherence. A current snapshot that enumerates competitors, so it subsumes a separate competitor list.

Params: subject_name (opt) : product/brand name to scope to; omit for workspace-wide.

get_competitor

One competitor deep dive: research profile (capabilities, positioning, differentiators), head-to-head W/L, per-engine W/L/T, per-capability W/L, top cited sources.

Params: competitor_name (req) : name from competitive_overview.

Diagnose → prove → fix → act

list_issues

The workspace’s Issues : the ranked diagnostic catalog of what AI gets wrong about you or where you’re losing, most-important-first. Each carries an importance_score (0-100). Light index; call get_issue for the proof, action, and linked playbooks.

Params: status (opt) candidate|open; issue_type (opt) misrepresentation|feature_gap|visibility_gap|source_gap; subject_name (opt); limit (opt, default 20, max 50); offset (opt).

get_issue

One issue’s verbatim proof + what to do.

  • Answer-grain (visibility/competitor gaps): the backing answers : each row’s evaluation_id, prompt_text (the buyer question), engine, outcome, coverage. Pass an evaluation_id to read_evaluation for the full AI answer.
  • Claim-grain (misrepresentation, source leak, negative sentiment, capability loss): the exact claims AI made : verbatim_quote, verdict, severity, engine, source URL. The API retains its established feature-oriented enum values.
  • Plus recommended_action, fixability (grounded = editable page vs parametric = baked into the model), and linked_playbooks.

Want the questions that track a fix? Each linked_playbook has an id : pass it to get_playbook with include=["questions"] for its tracked_prompts (worst first).

Params: issue_id (req) : from list_issues.

read_evaluation (read an Answer)

The full AI answer behind one scored Answer: the raw response_text plus the judge’s extraction : score, competitive_outcome, positioning_accuracy, sentiment, capabilities mentioned/missing, recommendation. The API keeps its established read_evaluation, evaluation_id, and tracked_prompts field names even though the console labels these objects Answers and Questions.

Id-anchored only (no free-form workspace search) so the agent stays on the diagnose → prove → fix path. Responses >6,000 chars are truncated (truncated: true, response_length total) : hand the id to your client’s fetch tool for the unabridged text.

Params: evaluation_id (req) : from get_issue’s example_evaluations or get_playbook’s tracked_prompts.

list_playbooks

The Playbooks : the fixes for your issues : ranked highest-ROI-first. Defaults to active work (proposed, in_progress). Each carries its ramp phase (fix-now, create-for-coverage, deepen, earn) and phase_label. The response top level carries the workspace’s ramp stage (estimated: true when computed on partial data : treat the roadmap as provisional) and a generating_count of playbooks still being drafted.

Params: statuses (opt, default ["proposed","in_progress"]) : pass ["shipped"] to see shipped (dismissed is internal-only); playbook_types (opt) comparison_page|feature_page|correction|third_party|refresh|icp_content; limit (opt, default 20, max 50); offset (opt).

get_playbook

Everything needed to draft the content for one playbook : most importantly the exact buyer keywords and terms to write with. Sections selected by include; omit it for the full drafting payload (keywords, brief, page-to-beat, critique, receipts).

The questions section is the questions the play is measured against (tracked_prompts, worst first) : opt in with include=["questions"]. This is how an agent finds the questions linked to an issue once it lands on the play that addresses it, and where the evaluation_ids for read_evaluation also live.

Params: playbook_id (req) : from list_playbooks or a linked_playbook.id; include (opt) : subset of keywords, brief, page_to_beat, critique, receipts, questions. Omit for the full set excluding questions; pass a narrow subset to fetch one slice fast.

update_playbook_status

Update a playbook’s status : the one write tool. Changes appear in the console.

Params: playbook_id (req); new_status (req) in_progress|shipped|dismissed; shipped_url (req when shipping content plays) : URL where content was published (earn-verb plays ship as “outreach sent” with no URL; an optional evidence link is stored but never treated as an owned page); dismissed_reason (req when dismissing) : ignored, or a granular irrelevant|wrong_evidence|already_done|bad_target|too_much_effort|other.

That’s the full set. Internal (superadmin-only) tools : coverage matrices, the topic ontology, the question library listing, score-trend history, and more : are hidden from customer callers by the curation allowlist and not listed here. One can be promoted to the customer surface deliberately when a real agent workflow emerges for it.

Next: how gaps become issues and playbooks, or back to connecting your AI tools.