# Using the tools > The DevHub tools by group: what each is for, the arguments that matter and the error you are most likely to see. This page groups the tools by purpose. Every tool, with all parameters, is in the [catalog of DevHub tools](/devhub/reference/mcp-tools/index.md). A star marks a required argument. Which tools you get depends on the user's Settings and plan; see [Limits](/devhub/for-agents/limits/index.md). Most list and search tools take `format` and `tokenBudget`. Raise `tokenBudget` when a result says it was cut. ## Context | 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` | | ## Finding your way | 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 | | | ## Knowledge and vaults | 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. ## Repository files | 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 | ## Repository index 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`. ## Plans and investigations | 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`* | | ## Agents | 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 …" | ## Library, memory and learning | 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 `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 `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. ## Related - [Catalog of DevHub tools](/devhub/reference/mcp-tools/index.md) - [Workflows](/devhub/for-agents/workflows/index.md)