MCP tool reference

The exact signature of every tool an agent sees: 14 tools, generated from the MCP server's own list_tools() response, so it cannot drift from the code. Each tool's text is reproduced verbatim — it is what the agent reads when deciding which tool to call.

See MCP server for connecting a client, the response envelope, the token budget and the built-in playbook.

Where the bounds come from

The schema an agent receives is derived from the handler signature, so it carries types and defaults but no bounds. The bounds column comes from the argument model the server validates against: exceeding one is a validation error, not a silent truncation — with the single exception noted on cograph_retrieve.

Rules that span two parameters cannot live in a per-parameter table, so they appear as bullets under it. Read those before calling a tool whose arguments are all optional: cograph_outline has two, and requires exactly one.

Orientation

Called first, to find out what exists and where to look. Cheap — these return names, structure and scores rather than ranked search results. cograph_repository_readme is the one that returns a document body, because knowing what a repository is for is the point of orienting.

cograph_repositories

List repositories readable by the authenticated MCP user. Returns compound slugs (host/owner/name) and the wiki resource URI. There is no graph resource URI — use cograph_search_code / cograph_read_node / cograph_related for the graph.

Use when: target repo is unknown — start here to enumerate, then feed the slug into the other tools.

Do NOT use to read a repo's docs (use cograph_repository_readme) or to search inside a repo (use cograph_retrieve / cograph_search_code).

Parameter	Type	Required	Default	Bounds
search	string	no	—	—
status	pending | cloning | indexing | embedding | generating | ready | error | deleting	no	—	—
limit	integer	no	100	1–100

cograph_collections

List markdown collections readable by the authenticated MCP user.

Use when: target collection_id is unknown — start here to enumerate.

Do NOT use to read a collection's documents (use cograph_collection_document) or to search inside a collection (use cograph_collection_search).

Parameter	Type	Required	Default	Bounds
search	string	no	—	—
limit	integer	no	100	1–100

cograph_route

Locate the repositories and markdown collections most likely to contain the answer to a natural-language query. Returns up to top_k candidates per kind with a score in [0, 1] and a one-line why explanation.

Use when: the user's question does NOT name a specific repository or collection — call this first, then fan out to ALL high-confidence candidates (score ≥ 0.7) with cograph_outline / cograph_retrieve. Facts routinely span sources; collapsing to a single candidate is a bug.

Do NOT use when the user already named a slug (skip straight to cograph_outline + cograph_retrieve with repository=<slug>), and do NOT use as a substitute for cograph_retrieve — route returns pointers to sources, not snippets.

Parameter	Type	Required	Default	Bounds
query	string	yes	—	non-empty, ≤ 512 chars
top_k	integer	no	3	1–10

cograph_outline

Token-cheap structural overview: top-level dirs + wiki page titles for a repo, OR document titles + heading sketches for an md collection. ≤ 30 items per section.

Use when: agent has just resolved a repo/collection and needs to know what's inside before any retrieval call. One-shot bootstrap.

Do NOT use to read content (use cograph_repository_readme / cograph_collection_document) or to search (use cograph_retrieve).

Parameter	Type	Required	Default	Bounds
repository	string	no	—	—
collection_id	uuid	no	—	—

• Pass exactly one of repository or collection_id. Both optional in the schema, but omitting both — or supplying both — is an INVALID_REQUEST error.

cograph_repository_readme

Fetch the canonical README/Overview document for a repository in one call.

Use when: the agent has a repo slug and wants to know what the project does, its scope, or how to use it. Falls back to the compacted wiki Overview (lead + section headings) if no README-named file is indexed.

Do NOT use to search inside the readme (use cograph_retrieve mode='wiki') or to read other docs (use cograph_collection_search / cograph_read_chunk).

Parameter	Type	Required	Default	Bounds
slug	string	yes	—	—

Search

Ranked candidates within one source. Returns snippets, not whole files.

cograph_retrieve

Hybrid search across code, AST summaries, and repo docs of one repository. Returns query-anchored excerpts with citations and a total_tokens_estimate so the agent can self-budget.

top_k bounds the number of results (clamped to 25); each result is a distinct hit, so start at the default 10 and only raise it if the answer is genuinely spread across many files.

repository is required — retrieval is always scoped to a single repository slug. If you don't know which repository holds the answer, call cograph_route first and retrieve from each candidate it returns.

Use when: the user asks a natural-language question and needs file-anchored snippets back. Pick mode='code' for 'where is X implemented', mode='wiki' for 'what is the auth flow about', mode='mixed' only when the target is unclear.

Do NOT use for symbol-exact lookups (use cograph_search_code) or to read a known node fully (use cograph_read_node).

Parameter	Type	Required	Default	Bounds
query	string	yes	—	non-empty
repository	string	yes	—	non-empty
mode	code | wiki | mixed	no	mixed	—
stores	(ast | code | ast_summary | repo_doc)[]	no	—	—
top_k	integer	no	10	≥ 1, silently clamped to 25
snippet_chars	integer	no	600	80–4000
as_of	date-time	no	—	—
since	date-time	no	—	—
until	date-time	no	—	—
include_chunks	boolean	no	true	—
include_graph	boolean	no	false	—
include_scores	boolean	no	false	—

• since must be earlier than or equal to both until and as_of.
• A non-empty stores replaces the layer set mode would have selected. An empty list is accepted and ignored — mode still decides — so omit stores rather than passing [] to mean “nothing”.

cograph_search_code

Lexical + fuzzy symbol search over a repository's code nodes. Returns names + line ranges (no body) so the agent can pick the right node, then read it with cograph_read_node.

Use when: agent has a probable symbol name (class, function, qualified path) and wants a symbol-exact lookup.

Do NOT use for natural-language questions (use cograph_retrieve with mode=code) or to read a node fully (use cograph_read_node).

Parameter	Type	Required	Default	Bounds
repository	string	yes	—	—
query	string	yes	—	non-empty
top_k	integer	no	10	1–100

cograph_collection_search

Hybrid search inside one readable markdown collection. Returns query-anchored excerpts (snippet + content_truncated) per chunk with a top-level total_tokens_estimate.

Use when: agent has a known collection_id and a natural-language question targeting markdown content.

Do NOT use to search code/wiki across repositories (use cograph_retrieve) or to read a chunk fully (use cograph_read_chunk).

Parameter	Type	Required	Default	Bounds
collection_id	uuid	yes	—	—
query	string	yes	—	non-empty
top_k	integer	no	10	1–100
snippet_chars	integer	no	600	80–4000

Read

Exact content for something already identified by a search or an outline.

cograph_read_node

Read one code node's body with its AST citation. The body is a whitespace-collapsed excerpt of at most snippet_chars (default 600, max 4000), and content_truncated says whether anything was cut — if a node is larger than the maximum, read its line range with cograph_read_file_range instead.

Use when: you have a known node_id (typically from cograph_search_code or cograph_retrieve) and need the actual code, not a list of hits.

Do NOT use to search by name (use cograph_search_code) or to explore neighbours by graph (use cograph_related). Pass with_graph=true / with_summary=true / with_linked_docs=true only when you actually need the heavier payload — defaults skip them to keep tokens bounded.

Parameter	Type	Required	Default	Bounds
repository	string	yes	—	—
node_id	uuid	yes	—	—
with_graph	boolean	no	false	—
with_summary	boolean	no	false	—
with_linked_docs	boolean	no	false	—
snippet_chars	integer	no	600	80–4000

cograph_read_file_range

Read a 1-indexed line range of a source file by repo slug + path.

Use when: you have a file_path (typically from provenance on a cograph_retrieve / cograph_search_code / cograph_read_node result) and need a few dozen lines of surrounding context that a node-bounded read won't capture.

Do NOT use to dump whole files (the range is capped at 1000 lines) or to search by content (use cograph_retrieve).

Parameter	Type	Required	Default	Bounds
repository	string	yes	—	—
path	string	yes	—	—
start_line	integer	yes	—	≥ 1
end_line	integer	yes	—	≥ 1

• end_line must be greater than or equal to start_line, and end_line - start_line + 1 must not exceed 1000 — the cap is on the span, not on either endpoint.
• An end_line past the end of the file is clamped rather than rejected, and the response reports it via content_truncated.

cograph_wiki_page

Read ONE generated-wiki page — or a single named section of it — on demand. The body is cut at a line boundary after 12000 characters with structure preserved; content_truncated says whether that happened, and the fix is to re-read one section rather than to retry the page.

Use when: the summarized wiki (the cograph_wiki_tree resource) is too terse for a topic and you need a page's prose, diagrams, or code samples verbatim. page is a wiki slug from that summary's tree; pass section (a heading from that page's sections list) to pull just that section and save tokens.

Do NOT use as your first wiki read — start from the summarized wiki resource and pull full pages only for the few that warrant depth. Do NOT use to search code (use cograph_retrieve / cograph_search_code).

Parameter	Type	Required	Default	Bounds
repository	string	yes	—	—
page	string	yes	—	—
section	string	no	—	—

cograph_collection_document

Read one full markdown collection document with parsed metadata (headings, code blocks, tables, links). No truncation.

Use when: agent has a known document_id from a prior cograph_collection_search / cograph_outline call.

Do NOT use to find documents (use cograph_collection_search) or to read just one chunk (use cograph_read_chunk — cheaper).

Parameter	Type	Required	Default	Bounds
collection_id	uuid	yes	—	—
document_id	uuid	yes	—	—

cograph_read_chunk

Fetch the full content of one markdown collection chunk by id.

Use when: cograph_collection_search returned a hit with content_truncated=true and the agent needs the rest of the chunk.

Do NOT use to read whole documents (use cograph_collection_document) or chunks from a different collection — chunk_id is scoped to its collection by access check.

Parameter	Type	Required	Default	Bounds
collection_id	uuid	yes	—	—
chunk_id	uuid	yes	—	—

Traverse

Follow the code graph outwards from a node.

cograph_related

Traverse the caller/callee graph around a code node up to depth hops (max 2).

Returns nodes and edges, scoped by direction (callers, callees, or both), capped at 50 nodes. truncated: true means the neighbourhood exceeded the cap — narrow with direction or continue from a more specific node instead of asking for more.

Use when: agent has a known node_id (from cograph_search_code or cograph_retrieve) and needs to trace control flow — what calls it, or what it calls.

Do NOT use to find nodes by name (use cograph_search_code) or to read a node's body (use cograph_read_node).

Parameter	Type	Required	Default	Bounds
repository	string	yes	—	—
node_id	uuid	yes	—	—
depth	integer	no	1	1–2
direction	callers | callees | both	no	both	—