Docs Reference
Tool Reference
Research tools (web_search, web_read, web_request_access) and structured browser tools
(browser_snapshot, browser_fill_form, browser_submit, browser_tabs,
browser_select_tab, browser_close_tab) are documented in Browser & Research.
Public research uses the direct HTTPS transport; Chromium interaction is limited to explicit
local testing origins and requires structured approval for input and actions.
A tool is a capability the model can ask Blacksite to use: read a file, search the map, update a plan, or run a command. The request is structured, checked by the extension, and shown in the transcript.
This is a technical lookup, not required reading. You never call these tools directly. Knowing what exists can still help you ask for a capability clearly instead of hoping the agent improvises it.
Every family below is a real group in the tool catalog.
Workspace#
File and shell operations. The load-bearing ones.
| Tool | Purpose |
|---|---|
file_read |
Read a file, or a range of it |
file_write |
Write a whole file |
file_edit, file_edit_batch |
Surgical text edits, one or many |
json_edit |
Structured edit of a JSON document by pointer |
file_list, file_glob |
Directory listing and glob matching |
file_search |
Text and code search across the workspace |
file_move, file_copy, file_delete, file_mkdir |
Filesystem operations |
shell_run |
Run a terminal command |
process_start, process_status, process_read_output, process_send_input, process_stop |
Long-running processes: dev servers, watchers, REPLs |
workspace_refresh |
Re-sync the agent’s pending checks, the Codebase Map and diagnostics with what is on disk |
Edits are diffed and approved before touching disk. Shell commands are classified and gated — see Approvals & Safety.
The process family is what lets the agent start your dev server, read its output as it runs, send it input, and stop it — rather than blocking forever on a command that never exits.
workspace_refresh is for when the agent’s own bookkeeping falls behind the disk: a reminder to
test a scratch script it already deleted, or errors still shown for a file that is gone. It changes
no files, and it does not count as a check.
Code intelligence (LSP)#
Queries against your installed language servers. This is the family that separates “the agent pattern-matched on text” from “the agent asked the same thing your editor asks”.
| Tool | Purpose |
|---|---|
code_symbols |
Symbols in a file or across the workspace |
code_navigate |
Definition, references, implementations, type definition |
code_hierarchy |
Call hierarchy and type hierarchy |
code_hover, code_inlay_hints |
Types and signatures at a position |
code_diagnostics |
Errors and warnings |
code_insert, code_replace, code_replace_batch |
Language-aware edits targeted by symbol, not line number |
code_rename |
The editor’s own rename refactor |
code_actions |
Quick fixes and refactors offered by the language server |
code_format |
Format through the configured formatter |
The targeting model is worth understanding: these tools take a symbol name in preference to a
line number. src/agent-session.ts + ChatProvider.send is stable across edits in a way that
line 412 is not. Mutating tools refuse ambiguous matches and require exact disambiguation; read
tools can take the first match.
After every edit, diagnostics are collected and fed straight back — so the agent finds out it broke the build before you do.
Design detail in LSP Code Intelligence.
Codebase Map#
| Tool | Purpose |
|---|---|
map_overview |
Orient in the whole workspace: projects, areas, hubs, cross-service flows, structural findings |
map_find |
Enumerate files with filters and ranking |
map_relationships |
One hop out from a file, across every layer |
map_impact |
Transitive blast radius, N hops, with the edge chain back to the seed |
map_path |
Shortest concrete chains connecting two files |
map_note_add, map_note_list, map_note_update, map_note_remove |
Durable annotations on files and relations |
Covered fully in Using the Codebase Map.
Work graph#
Offered only while blacksite.orchestration.workGraph is on.
| Tool | Purpose |
|---|---|
work_graph |
Read-only questions across tickets, plan steps, the code they touch, and the receipts and runs that are evidence for them: trace, blockers, dependencies, dependents, impact, critical_path, conflicts, findings |
Every relation is marked with where it came from:
- verified: observed by the extension, such as a receipt’s changed files;
- declared: written in a ticket, plan or contract;
- inferred: worked out by the graph, such as step order or overlapping territory;
- missing: its target no longer exists.
Evidence that later changes have overtaken is marked stale. findings lists dependency cycles, missing references, stale evidence, inputs a newer receipt replaced, and ticket links the ticket store dropped when reading. Nothing is repaired.
Planning#
| Tool | Purpose |
|---|---|
plan_create, plan_update, plan_list |
Multi-phase plans and their state |
plan_doc_write, plan_doc_read, plan_doc_list |
Documents attached to a plan or phase |
todo_create, todo_update, todo_status, todo_list |
Lightweight in-session checklists |
Tickets#
| Tool | Purpose |
|---|---|
ticket_file |
Record an out-of-scope outcome without widening the current task |
ticket_list, ticket_update |
Find and maintain work in the local queue |
ticket_get |
Read one ticket in full, including its whole comment history |
ticket_comment |
Add durable findings or decisions to a ticket’s activity timeline |
ticket_next |
Rank unblocked work and explain why it rose to the top |
ticket_promote |
Turn a ticket’s outcome and map territory into the seed for a plan |
ticket_sweep |
Propose triage candidates from existing diagnostics and TODO markers (never files them) |
See Tickets & the Board for the everyday workflow.
Diagnostics#
| Tool | Purpose |
|---|---|
report_problems |
Publish findings into the VS Code Problems panel |
The agent can put its findings where you already look for problems, instead of only in chat. Clear them with Blacksite: Clear Problems.
Memory#
| Tool | Purpose |
|---|---|
memory_append, memory_read, memory_search |
Durable project knowledge across sessions |
Skills#
| Tool | Purpose |
|---|---|
skill_read |
Load a stored procedure into the working context, or read a file it bundles |
skill_list |
The full catalog with origin, availability, and load state |
skill_write |
Capture a repeatable procedure as a workspace skill |
A skill is a SKILL.md — frontmatter plus a procedure — that the agent loads when the work
matches its description. The agent sees a one-line roster of what is available in its workspace
state each turn; loading pulls the full body into context for the rest of the session, so each
skill is read once.
Skills resolve workspace → personal → built-in by name, so .blacksite/skills/<name>/ in a
repository beats a personal copy in ~/.blacksite/skills/, which beats one that ships with
Blacksite. skill_write only ever writes into the workspace: it refuses a name a personal skill
owns, and a name a built-in uses produces a shadowing workspace copy rather than an in-place edit
the next update would erase.
Manage them in the Skills panel, which lists every skill with its origin and lints a new one as you write it. See Plans & Context for how skills differ from Base Context and project memory.
Data#
db_list_objects, db_describe_object, db_preview_rows, db_run_read_query,
db_preview_write_query, db_vector_search, db_list_saved_queries — see
Data Workbench.
References (attachments)#
| Tool | Purpose |
|---|---|
reference_list, reference_read |
List attachments (with the workspacePath file_read accepts; allConversations includes other conversations) and read PDF page ranges or other extracted documents |
reference_search |
Deterministic page-numbered search within a PDF, without requiring embeddings |
reference_zoom_image |
Inspect a region of an image at higher fidelity |
reference_query_spreadsheet |
Query a spreadsheet as data |
reference_vector_search |
Semantic search across attachments |
reference_context_read, reference_context_write |
Durable notes about an attachment |
Attachments are stored on disk and retrieved on demand rather than pasted into context. PDFs are indexed page-by-page in the background, so the agent can inspect their structure, search for a passage, and read only the relevant range without consuming the context window with the whole file.
Git, tests, worktrees#
| Tool | Purpose |
|---|---|
git_op |
Status, diff, log, blame, branch, stage, commit |
test_detect |
Work out how this project runs tests |
test_run |
Run them, scoped |
worktree_op |
Manage git worktrees for isolated parallel work |
test_detect before test_run is the pattern that makes this work across projects with different
runners.
Subagents#
| Tool | Purpose |
|---|---|
subagent_spawn |
Run independent work in a separate context and return the result |
subagent_followup |
Resume a finished lane with a new message, keeping its context |
With work contracts on (blacksite.orchestration.workContracts), subagent_spawn takes an optional contract. It can narrow what the lane may change and spend, and add deliverables and acceptance criteria. Anything wider than the lane would otherwise get, or any field not in the schema, refuses the spawn. The result then carries a receipt:
- what the extension observed the lane change;
- which checks covered those changes;
- a status, kept separate from what the lane said about its own work:
verified,succeeded_unverified,partial,blocked,failed,cancelledorabandoned.
Used for inspection, verification, broad file triage, and evidence gathering — so the parent agent preserves its context for orchestration and synthesis. Four built-in profiles: Frontend UI, Backend API, QA Regression, Repo Ops.
Complexity sets the budget#
Every lane is rated standard, complex, or deep, and that rating sets its time and
tool-round budget. The rating reflects the work required rather than the length of the
request — a one-line task can be the deep one.
| Rating | Suits | Roughly |
|---|---|---|
standard |
A bounded lookup or single-file change | Under 6 tool calls |
complex |
Multi-file investigation, or a change needing verification | 6–10 tool calls |
deep |
Broad triage in unfamiliar territory, or iterative build/test cycles | 10+ tool calls |
Sequential and parallel#
Both are first-class, and the agent picks per situation:
- Sequential (the default) runs one lane at a time. Often the right call: the first result frequently changes what the second task should even be, and it keeps synthesis to one thing.
- Parallel fans out several lanes issued in the same turn, each marked
parallel: true, up to Max concurrent in Settings → Subagents. Worth it when the lanes are genuinely independent and wall-clock time is what you want back.
The trade runs in both directions: fanning out pays for every lane’s context even when the first answer makes the rest moot, and lands several results at once to synthesise. Sequencing pays the sum of the latencies rather than the slowest one. Lanes that would write to overlapping files stay sequential.
When a lane does not finish#
A lane that runs out of time or ends without an answer returns what it gathered rather than
just a status: partialAnswer, executionTrace, filesTouched, toolRounds, and a
failureKind of timeout, cancelled, no_answer, or error.
That distinction shapes what happens next. A timeout was still making progress when its
budget ran out, so it is worth resuming or re-running narrowed. A no_answer ran to
completion, so the same request would land the same way and is better restated. Frequently
partialAnswer already covers the task and no further lane is needed.
Following up#
subagent_followup re-opens a finished lane using the subRequestId from its result. The lane
still holds the files it read and the reasoning behind its answer, so a follow-up costs a single
message where a new lane would start from nothing. Follow-ups run one at a time, get their own
budget, and the most recent lanes stay resumable.
Transcript and result paging#
| Tool | Purpose |
|---|---|
transcript_read |
Read back earlier in the current conversation |
transcript_document |
Write a long deliverable as a navigable document |
tool_output_page |
Page through a large tool result |
tool_output_search |
Search within a large tool result |
The paging family is why one enormous grep result cannot exhaust your context window.
Diagrams#
| Tool | Purpose |
|---|---|
diagram_check |
Check Mermaid source, or a chart block, and get the parser’s line and an excerpt on failure |
diagram_read |
List the diagrams saved with the project, or read one with line numbers |
diagram_save |
Save a diagram to .blacksite/context/diagrams/, refused unchanged if it does not parse |
diagram_edit |
Change a saved diagram by exact text, line range or insertion, all-or-nothing and checked before saving |
These keep a large diagram editable without rewriting it. diagram_check runs Mermaid’s real parser
in a background worker, so it costs nothing until it is first used. Saving and editing write only
inside .blacksite/, never your source tree, so they stay available in plan mode.
Service integrations#
Read/write operations against external systems, when configured:
- GitHub — issues (list, get, create, comment), pull requests (list, get, get with full diff/review/discussion context, create), branches (list), files (get), and code search
- GitLab — the equivalent surface for merge requests and issues, plus branches (list) — no project-listing tool
- Jira — issues (search via JQL, get, create, update, comment), and projects (list)
- Confluence — pages (get, create, update), spaces (list), and content search (CQL)
- Salesforce — objects (get, create, update, list), and SOQL queries
Execution Runs#
| Tool | Purpose |
|---|---|
sequence_discover |
Find routes, stories, tests, files, and reachable local surfaces |
sequence_execute |
Execute one approved, bounded linear sequence and retain its evidence |
sequence_inspect |
Seek to a step, event, anomaly, checkpoint, entity, or semantic match without rerunning |
sequence_compare |
Align two runs and report channel-scoped candidate differences |
sequence_resume |
Conservatively replay a repeatable setup/tail; marker-only checkpoints and unsafe effects are rejected |
sequence_search |
Search run history by text, lineage, work item, surface, file, status, or anomaly |
sequence_annotate |
Create or update a durable note anchored to retained run evidence — a finding, decision, or disposition that should survive the current turn |
These tools return compact IDs and summaries; full event windows and artifacts stay local until the agent asks for a focused inspection. Browser sequences are limited to loopback development origins, and process actions use the same approval policy as their standalone equivalents.
Browser#
| Tool | Purpose |
|---|---|
browser_navigate |
Open a URL |
browser_click, browser_type |
Interact with the page |
browser_get_text, browser_screenshot |
Read what is there |
browser_evaluate, browser_run_script |
Execute JavaScript in the page |
Runs headed by default so you can watch what it does — set blacksite.browserHeadless to true to
hide the window. Close it with Blacksite: Close Browser Window.
Headed is the better default. An agent driving a browser invisibly is an agent you cannot correct.
UI#
| Tool | Purpose |
|---|---|
question_card |
Ask a structured question with options, implications, and optional previews |
ui_design_tokens |
List the project stylesheet’s tokens, component classes and font stacks for use in previews |
ui_preview_render |
Render a preview headlessly at the frame size it will be shown at, and return the screenshot |
ui_preview_render runs in its own headless browser context, separate from the agent’s browser
session, and asks for no approval: the document is one Blacksite built and serves itself on a
private loopback address, with no network access.
Preview code can use JSX and react/react-dom even in a project that does not install React:
Blacksite ships a copy of React for previews and uses it only when the workspace has none of its
own. Any other package a preview imports must be installed in the workspace. Like the card
itself, the render blocks eval and new Function.
MCP#
| Tool | Purpose |
|---|---|
mcp__<server>__<tool> |
Each tool you admit from an enabled MCP server, under its own name, with the server’s description and argument schema |
mcp_list_tools, mcp_call_tool |
List and call a server’s tools by name, for a server whose tools have not been discovered yet |
mcp_list_resources, mcp_read_resource |
List and read the documents and records a server publishes |
The agent calls an MCP tool the way it calls a built-in one, by name and with typed arguments, and it loads MCP tools on demand like other tool families, so a server with many tools costs one line in the tool roster until one of them is needed. Images a tool returns are shown to the model. Blacksite discovers enabled servers’ tools in the background and re-lists a server when it says its tools changed.
Which tools an MCP server contributes is yours to decide per tool, in Blacksite: Manage MCP Servers. A tool you switch off is removed from the catalog the agent receives — same as a disabled tool family below, the model is not told it exists.
Turning families off#
Tool group toggles live in the Blacksite settings. Disabling a family removes those tools from the catalog entirely — the model is not told they exist, so it cannot ask for them and cannot be disappointed.
Worth doing when a family is irrelevant to your work: fewer tools is a smaller prompt and a smaller decision space.
Related#
- Working with Chat — how tools show up in the transcript
- Approvals & Safety — which calls are gated
- Provider-Neutral Agent Environment — how tool schemas are converted per provider