How the tools fit together
A typical session walks through these stages:- Discover. Call
list_knowledge_storesto pick a knowledge store. Theidyou get is theproject_idevery other tool needs. - Inspect. Call
list_knowledgefor the artifact catalog (cohesion guide plus one row per artifact),library_tags_objectsfor tag hierarchies and object schemas, and the matchingget_*_artifacttool to read one artifact in full. - Run. Call
list_toolsfor the catalogue,get_toolto read the input schema of the one you want, thenrun_toolto execute. Every claim in the answer should carry an inline reference link back to the source. - Feedback. When the user complains or corrects, call
create_feedbackto push the signal into the knowledge store’s feedback queue. - Review. When acting as a contributor, use
list_feedback,list_conversations, andlist_interviewsto triage signals, thenget_*to read the detail. Close the loop on addressed items withresolve_feedback. - Interview. Draft new interviews with
draft_interviews(optionally grouped under a campaign), keep them current withlist_interview_draftsandupdate_interview_draft, and bring external conversations in withimport_interview_transcript. Sending always stays a human action. - Edit. Apply improvements directly with the
set_*_artifacttools matching each artifact’s technical type.
Discover
list_knowledge_stores
Lists the knowledge stores the current token can access. Returns [{id, name, brief}].
Typically the first call in a session. Pick one — its id is the project_id every other tool needs.
list_teammates is a deprecated alias kept for existing clients (“teammates” was the former name for knowledge stores); prefer list_knowledge_stores.
whoami
Returns information about the currently authenticated user. Thin wrapper over the REST users/me endpoint.
Useful for sanity-checking auth, surfacing the user’s email in a session preamble, or branching behaviour by user.
Inspect
list_knowledge
Catalog overview of a knowledge store. Returns the cohesion_guide (cross-artifact consistency rules) and artifacts[] — one row per in-scope artifact with slug, title, semantic_type, technical_type, group, purpose, and either the full content (e.g. markdown artifacts) or a content_overview summary (playbooks, mental map, design templates).
group is the artifact’s catalog section: Foundation for predefined artifacts, the curator’s group name for custom ones, Other when a custom artifact is ungrouped. Use it to present the catalog the way curators organized it.
Call this before drilling in. If a playbook matches the user’s question, read it in full with get_playbook_list_artifact and follow its steps.
library_tags_objects
Warehouse tags and object schema for the document library. Returns markdown sections tag_hierarchies, document_tags, and knowledge_graph_objects.
Use it to refine retrieval: the tags and object classes it lists are the filters the retrieval tools accept.
list_knowledge_changelog
Lists the knowledge store’s changelog entries, most recent first. Returns {count, results}; each entry carries a human-readable description, structured details, and the acting user_email.
Use it to see what changed recently — document uploads, artifact edits — before summarizing knowledge store activity or diagnosing a stale answer.
get_markdown_artifact and friends
Read one artifact in full. Pick the get_* tool matching the artifact’s technical_type from list_knowledge and pass its slug:
get_markdown_artifact— markdown artifacts (e.g.brief,general_knowledge,library_description).get_playbook_list_artifact— the playbook list (typicallyplaybooks).get_mental_map_artifact— the mental map.get_design_template_list_artifact— design templates, including their files.get_bpmn_xml_artifact— custom BPMN 2.0 process diagrams.
Run
list_tools
Brief catalogue of the knowledge store’s tools. Returns [{id, name, tool_type}] — intentionally minimal so the listing stays cheap.
For the full metadata, including the input schema, call get_tool on the one you want.
get_tool
Full metadata for one tool. Returns the input_schema (JSON Schema), the tool type, and a description augmented with a type-specific usage guide.
Always call this before run_tool for an unfamiliar tool — the schema is the source of truth for what arguments to pass.
run_tool
Executes a tool against the knowledge store. Takes a tool id and an input dict that matches the tool’s input schema.
On failure, returns a structured error object including expected_input_schema (re-fetched) and a hint to retry — no exception is raised. Use that to self-correct: re-read the schema, fix the input, call again.
Not the right tool for submitting feedback — use create_feedback.
Feedback
create_feedback
Submits feedback to the knowledge store’s feedback queue. Takes a flat, LLM-friendly payload (type, is_positive, user_query, reason, …); the server restructures it into the backend’s shape and tags the source as MCP.
Use it whenever the user complains, corrects, or confirms — it lands as a signal that Contributors pick up and use to update artifacts or sources.
list_feedback
Lists feedback items in a knowledge store. Returns {count, results} — up to limit rows (default 50); raise limit to page further.
Filter by status ("to_review", "reviewed", "dismissed") and is_positive to focus on what matters. For triage, pass is_positive=false and status="to_review" to surface unactioned negative signals. Each row carries the linked conversation id and a user_message preview. Call get_feedback then get_conversation to deep-dive an exchange.
get_feedback
Gets a single feedback item, including the linked conversation id.
The reviewer’s note is in the feedback field and the end-user’s message in user_message. Follow the returned conversation id with get_conversation to read the full transcript that produced the signal.
resolve_feedback
Closes the loop on a feedback item once it has been addressed.
Pass status="reviewed" when you acted on it (e.g. by editing an artifact) or status="dismissed" for won’t-fix. The artifact edit itself is the audit trail of how it was addressed.
Review
list_conversations
Lists end-user playground conversations in a knowledge store. Returns {count, results} — lightweight rows with first_user_message, message_count, tags, and feedback_count. Returns up to limit rows (default 50).
Use for triage — pick conversations worth reading in full, then call get_conversation.
get_conversation
Gets a single conversation with its full chat_history.
Use to read the exchange a feedback refers to (follow the conversation id from get_feedback), or to inspect an end-user conversation in detail.
list_interviews
Lists interviews (coach conversations) in a knowledge store. Returns {count, results} — lightweight rows with name, status, first_message_preview, and message_count. Returns up to limit rows (default 50).
Filter by status ("pending", "in_progress", "completed", comma-separated for several) to narrow scope. Rows include imported external transcripts (type "imported-interview"); their import_info.import_status must be "ready" before the transcript is readable. Use for consensus/contradiction triage — pick interviews worth reading in full, then call get_interview.
get_interview
Gets a single interview with its full chat_history.
Besides the transcript, the response carries the interview’s setup: interview_focus ({topic, questions} — what the interviewing agent was briefed on) and, for guided interviews, topics (the ordered agenda, each {title, description, status, skill_id}; empty for other types). Use it to read the full exchange for analysis, understand what an interview was meant to cover, or reuse its setup when drafting a similar one.
Imported transcripts carry a per-message speaker name. A merged label like “Them” or several names means the export did not attribute those lines to one person — never present merged-speaker statements as one named individual’s words.
Interview
Drafting tools never send anything: a draft only becomes real interviews when a human reviews and sends it from the interviews page. Always end a drafting exchange by handing the user the returneddraft_edit_url and telling them to review and send.
draft_interviews
Drafts (but never sends) an interview for a set of recipients.
Two kinds: a single-topic interview (5–10 minutes, the default) opens on the focus and lets the interviewer ask follow-ups — optionally seeded with specific questions (max 10). A guided-interview walks an ordered topics agenda (max 12, each {title, description}) at roughly 5–10 minutes per topic — pick it only for broad, structured coverage, and agree the topic list with the human first.
Recipients can be existing members or new email addresses; new addresses are only invited to the store if the human sends the draft. language pins the interview to an ISO language code when the human asks for one. campaign_name groups the interview under an interview campaign (e.g. a workshop wave or rollout round) — it reuses the project’s existing campaign with that name (case-insensitive) or creates it; only set it when the human names a campaign or clearly groups several interviews together.
Each call creates a fresh draft — to change an existing one, use update_interview_draft instead of re-drafting.
list_interview_drafts
Lists saved, unsent interview drafts in a knowledge store. Returns {count, results}, newest-edited first; each row carries the draft’s topic, questions, topics (guided drafts), recipients, settings, and a draft_edit_url.
Check it before drafting a new interview to avoid near-duplicates, or when the human asks what’s pending. For sent or completed interviews use list_interviews instead.
update_interview_draft
Updates one saved draft in place — still never sends anything.
Prefer it over draft_interviews when the human wants changes to an existing draft. Only the fields you pass change; the draft’s interview type is immutable. focus, questions (single-topic drafts), topics (guided drafts), recipients, custom_message, and language can all be replaced. campaign_name moves the draft to that campaign (creating it if needed); pass an empty string to remove the draft from its campaign.
import_interview_transcript
Imports the transcript of an interview that happened outside the platform (a Granola, Teams, or Zoom export, meeting notes with speaker turns, …).
Creates a read-only imported interview; parsing into speaker-labeled turns runs in the background (import_info.import_status goes from "parsing" to "ready"). Pass the transcript text verbatim — never summarize, trim, or reformat it — and call the tool once per transcript. title, participants, and interview_date are optional; anything omitted is inferred during parsing.
Edit
Writes require admin permission on the knowledge store. Each artifact type has a matchingset_* tool — pick it by the artifact’s technical_type from list_knowledge, and always read the current content with the matching get_* tool before writing. Pass a change_summary stating what changed and why, and cite the interview or feedback evidence behind the change.
set_markdown_artifact
Edits a markdown artifact (brief, general knowledge, library description, custom markdown artifacts). Takes an op — replace the whole text, replace a line range, or replace a matched text occurrence — plus new_text.
set_playbook_list_artifact
Edits the playbook list. Takes an identifier (the playbook), a change_summary, and an ordered changes list. Apply changes in order — add steps before the links that reference them. Failed individual changes are skipped and reported per-change without aborting the rest.
set_mental_map_artifact
Edits the mental map. Takes a change_summary and an ordered changes list over domains, classes, and relations. Add domains and classes before the relations that reference them; deleting a domain or class also removes dependent entities.