Using the tools

This page groups the tools by purpose. Every tool, with all parameters, is in the catalog of DevHub tools. A star marks a required argument. Which tools you get depends on the user’s Settings and plan; see Limits.

Most list and search tools take format and tokenBudget. Raise tokenBudget when a result says it was cut.

Tool	Use it to	Key arguments	Typical error
context_pull	take what the user queued for you: vault notes, symbols, overviews. Empties the queue	peek, ids, tokenBudget	an item reported as missing stays queued; the file or symbol moved
context_get	read the same payload without emptying the queue	peek, ids

Tool	Use it to	Key arguments	Typical error
workspace_list	list repositories you may touch, with project, organization and suggested vault	organization, project, q
vault_list	list vaults you may read or write, with scope and access

Tool	Use it to	Key arguments	Typical error
vault_overview	see folders, what belongs in each, note counts	vaultId*
knowledge_search	ask a vault: decisions, rules, “why”. Reads the knowledge folders only; a miss is not absence	query*, vaultId or workspaceId, knowledgeType, limit	empty result: try vault_files_search, or check knowledge_index_status
rag_context	assemble grounded context for one question, split by authority	query*, vaultId
knowledge_get	read one search hit in full	id*, same ids as the search
vault_files_search	find a note anywhere in one vault by words in it	query, vaultId, type, tags
vault_files_list	browse one folder	vaultId*, path
vault_file_read	read a note, whole or a line range	vaultId, path
vault_file_replace, vault_file_edit, vault_file_write, vault_file_create, vault_file_properties	change a note: exact text, line ranges, whole note, new note, front matter	vaultId, path	“Vault is not configured for MCP write access”
vault_open	show a note to the user in the Vault Viewer	vaultId*, path
knowledge_index_status, knowledge_index_refresh	check that Business Context is indexed; rebuild after you edit notes	vaultIds

Prefer vault_file_replace for edits. vault_file_write overwrites and discards what you did not include.

Tool	Use it to	Key arguments	Typical error
files_list, files_search	browse a folder; search text	workspaceId, path, query
file_read	read a file, whole or a line range	workspaceId, path, offset, limit	a partial read says so in its header; do not overwrite from it
file_replace, file_edit	change known text; change known line ranges	expectedHash for file_edit	hash or text mismatch: read again
file_create, file_write, directory_create	create a file (fails if it exists); create or overwrite; create a folder	workspaceId, path	“already exists” on file_create
file_delete	delete a file or folder. Irreversible; ask the user first	recursive	needs the manage level
asset_read, asset_write	read or write a binary file as Base64, up to 20 MB	base64*, mimeType
npm_script_list, npm_script_run	list and run declared package scripts. No arbitrary commands	script*, timeoutMs, ci	a script that is not declared is refused; running needs the manage level
display_list, display_screenshot	see what the user sees	displayId*	needs the manage level

Call repo_index_status first; call repo_index_refresh if it is stale.

Tool	Use it to	Key arguments
repo_overview	map subsystems and the most connected symbols	limit, tokenBudget
repo_symbol_search	find a definition by name, signature, kind or path	query*, kind, path, includeTests
repo_symbol_get	confirm one symbol	symbolId*
repo_callers	who calls a symbol	symbolId*
repo_references	every reference, also unresolved ones; use when callers looks too short	symbolId*
repo_neighbors	everything directly connected	symbolId*, direction, kind
repo_impact	what breaks if a symbol changes	symbolId*, depth
repo_file	a file’s symbols, imports and importers	path*
repo_routes	HTTP routes and Electron IPC channels	query
repo_changed	how much the last rebuild re-read
repo_unnamed_subsystems, repo_name_subsystems	name groups the index left unnamed	names*

All of them need workspaceId. Take symbolId from repo_symbol_search.

Tool	Use it to	Key arguments	Typical error
investigation_list	see what was looked into before	q
investigation_create, investigation_add	open a spike; write a document in it (analysis, variant, plan, finding)	title, body
investigation_read	read one investigation or one document	id*, documentId
investigation_close	an agent cannot close one		“An agent cannot close an investigation”
plan_ready	what you may take now, and why the rest is blocked	planId
plan_claim	take a step exclusively; returns the step and a working tree	planId, stepId, by	refused: held, gate open, or same files in use
plan_renew	say you still work on it	planId, stepId
step_resume	read a step in full	planId, stepId
step_update, step_log	move a step on; log a stint	outcome* for step_log
plan_close	merge the working tree back and record the commits	commits, as	“Step not closed: …”
plan_create, step_add	open a plan; add a step	title, id	refused when the id is taken
plan_status	plan against what the repository shows	planId*

Tool	Use it to	Key arguments	Typical error
agent_list	see configured agents, and what agent_create accepts	workspaceId
agent_run	give a task to a configured agent	agentId, task	“RUNNING” is not a failure; starting an agent needs the manage level
agent_run_status	wait for a run	runId*, wait (0 to 45 seconds)	“No such run”
agent_create, agent_update	configure an agent. A new or widened agent is switched off until the owner switches it on		“No persona …” or “No client …”

Tool	Use it to
library_list, library_get	find a skill, rule, command, persona, profile or instruction that exists, and read it into this session
library_create, library_edit	write into the user’s own collection. Call library_list first
memory_note	store a standing fact about the work, the user or where things live
learning_note	store one lesson about why something went wrong

audit_summary answers “is anything broken right now”. audit_analyze finds repeated errors and slow tools. audit_list shows single calls with arguments, error and timing.

pet_persona: call once per session and keep the result. It says whether the persona applies to your replies. pet_say shows the user what you are doing; pet_status shows the pet’s current state.

• Catalog of DevHub tools
• Workflows