MCP tools reference

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 managed under Content → Interfaces in eligible workspaces.

The surface is deliberately lean and REST-style: list_* returns a paginated index (scalars only), and a matching get_* drills into one entity. Coverage matrices and the topic ontology 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 changes made via an assistant appear in the console.

Orient

Call get_workspace_context first so the assistant knows the workspace before it acts. If you need a different workspace, switch to it first.

get_workspace_context

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

list_workspaces and switch_workspace

Signed-in users can list their workspaces and switch the active one before using the other tools. The current Settings → MCP setup connects through browser sign-in.

Params: list_workspaces takes none; switch_workspace takes workspace (req), a workspace name, slug, or ID.

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

Two tools: the overall scorecard, then a deep dive on any one competitor named in it.

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.

add_competitor

Add a competitor to your brand or selected products. A name-only call adds it to the brand and starts background research. To save it without starting research, pass research=false. The tool returns the competitor ID, linked subject count, and research queue status.

Params: name (req) : company name; domain (opt) : website domain; subject_name (opt) : one brand or product name; subject_names (opt) : several brand or product names, in place of subject_name; competing_product_name (opt) : rival offering name used in product comparisons; source_urls (opt, up to 10) : public research pages; research (opt, default true) : start background research after saving. This tool requires intelligence:write.

For example, call add_competitor with name="Rival" to add it to the brand. To link it to two products, pass subject_names=["Product A", "Product B"]. Adding a competitor to a product that already has the profile links the existing profile to that product.

remove_competitor

Stop tracking a competitor across the brand and all products. This also archives its active comparison questions. The research profile stays available if you restore the competitor later. This tool requires intelligence:write.

Params: competitor_name (req) : name from competitive_overview.

get_weekly_digest

The latest weekly score, changes, and recommended next playbook. A provisional digest withholds comparative claims; a digest revised after composition may contain stale figures.

Params: period_id (opt) : a week in week-YYYY-MM-DD form. Omit for the latest available digest.

Manage questions

The console calls these Prompts; the MCP API retains the prompt names.

list_prompts

List active questions, with filters for competitor, category, buyer role, subject, capability, topic, or text. Page with offset when pagination.has_more is true.

Params: status (opt, default active) : active|archived|all; limit (opt, default 20, max 50); offset (opt); competitor_name, category, persona, subject_name, feature_name, topic_name, search (all opt).

create_prompt

Add one manual question. A duplicate returns the existing ID. The plan’s active question limit applies, and edits wait for a running benchmark to finish. Requires prompts:write.

Params: text (req); prompt_category (opt, default competitive) : competitive|visibility; competitor_name, feature_name, persona, subject_name, topic_name (all opt).

archive_prompt

Remove a question from future runs while keeping its results. Use list_prompts to find its ID. Requires prompts:write.

Params: prompt_id (req).

Diagnose → prove → fix → act

The tools below walk that path in order: find what’s wrong, see the exact proof behind it, then track and ship the fix.

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 Prompts.

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. 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 customer set. Internal (superadmin-only) tools, including coverage matrices, the topic ontology, and score-trend history, are hidden from customer callers by the curation allowlist and not listed here. One can be promoted to the customer surface when a customer workflow calls for it.

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