Tool reference
All 38 tools in the catalog, grouped by family. This page is generated from the catalog when the site builds; each description below is the exact text the server sends to a connected client, and the per-minute ceilings are the defaults a deployment can raise or lower per tool.
A deployment exposes families by setting ARROWHEAD_PROFILE; a tool outside the active profile is never registered.
| Profile | Families |
|---|---|
core |
core |
docs |
core, data, docs, memory, notify, tasks |
coding |
assist, context, core, data, exec, repo |
full |
every family |
| Tool | Scope | Per minute | Hints |
|---|---|---|---|
safe_fetch |
tools:read |
30 | read-only, open-world |
calculate |
tools:read |
120 | read-only |
read_file |
tools:read |
60 | read-only |
safe_fetch
Section titled “safe_fetch”Fetch a public http or https URL and return its status, content type, and body text. Private, loopback, link-local, and cloud metadata addresses are refused. Example: safe_fetch(url=“https://example.com/”).
calculate
Section titled “calculate”Evaluate an arithmetic expression with + - * / and parentheses. Example: calculate(expression=“2 * (3 + 4)”) returns 14.
read_file
Section titled “read_file”Read a text file from the server’s sandbox directory by relative path. Example: read_file(path=“notes/readme.txt”).
| Tool | Scope | Per minute | Hints |
|---|---|---|---|
doc_search |
docs:search |
60 | read-only |
doc_read |
docs:read |
60 | read-only |
doc_retrieve |
docs:read |
30 | read-only, open-world |
doc_scan |
docs:scan |
20 | read-only |
doc_write |
docs:write |
30 | destructive |
doc_search
Section titled “doc_search”Search corpus documents for a query and return bounded, sanitized snippets. Literal by default; set use_regex when enabled. Example: doc_search(query=“deadline”, path_prefix=“notes/”).
doc_read
Section titled “doc_read”Read a JSON, Markdown, or text document from the corpus by relative path. Returns sanitized content wrapped with provenance. Example: doc_read(path=“notes/todo.md”).
doc_retrieve
Section titled “doc_retrieve”Retrieve a JSON, Markdown, or text document from a public URL, SSRF-guarded and sanitized. Returns wrapped, untrusted content. Example: doc_retrieve(url=“https://example.com/data.json”).
doc_scan
Section titled “doc_scan”Scan corpus documents for secrets and PII and return redacted findings (type, location, and a hashed placeholder, never the raw value). Example: doc_scan(path_prefix=“exports/”).
doc_write
Section titled “doc_write”Write a JSON, Markdown, or text document to the corpus. Creates a new document; set overwrite to replace an existing one, which asks for confirmation. Example: doc_write(path=“notes/todo.md”, content=“# Todo”).
| Tool | Scope | Per minute | Hints |
|---|---|---|---|
sql_query |
sql:read |
60 | read-only |
vector_search |
vector:search |
30 | read-only |
vector_query |
vector:search |
30 | read-only |
hybrid_query |
vector:search |
30 | read-only |
doc_index |
vector:write |
6 | idempotent |
sql_query
Section titled “sql_query”Run a read-only SQL query and return its rows as untrusted data. Only a single SELECT may run; every referenced table is authorized, and results are capped. Bind values with named parameters. Example: sql_query(query= “select id, email from users where org = :org”, params={“org”: “acme”}).
vector_search
Section titled “vector_search”Find the nearest rows in a pgvector collection to a query embedding, scoped to the caller’s tenant. Only an allow-listed collection may be searched, the tenant is the caller, and results are capped. Example: vector_search(collection=“documents”, embedding=[0.1, 0.2, …], k=5).
vector_query
Section titled “vector_query”Find the corpus chunks most similar to a natural-language query, scoped to the caller’s tenant. The query is embedded server-side, only an allow-listed collection is searched, and each result carries its source document and chunk index as a citation. Example: vector_query(collection=“doc_chunks”, query=“how do refunds work?”, k=5).
hybrid_query
Section titled “hybrid_query”Retrieve corpus chunks by fused vector and keyword relevance, scoped to the caller’s tenant. The query is embedded server-side and also run as a full-text search; the two rankings merge by reciprocal rank fusion, so exact identifiers and paraphrases both surface. Example: hybrid_query(collection=“doc_chunks”, query=“refund window”, k=5).
doc_index
Section titled “doc_index”Index corpus documents into a pgvector collection so vector_query can retrieve them. Each document under the path prefix is chunked, embedded, and written under the caller’s tenant; a re-index replaces a document’s existing chunks and skips unchanged ones without re-embedding them. Example: doc_index(collection=“doc_chunks”, path_prefix=“handbook/”).
| Tool | Scope | Per minute | Hints |
|---|---|---|---|
code_search |
repo:search |
60 | read-only |
code_read |
repo:read |
60 | read-only |
symbol_map |
repo:read |
20 | read-only |
dependency_graph |
repo:read |
10 | read-only |
code_search
Section titled “code_search”Search repository files for a query and return bounded, sanitized snippets with line numbers. Literal by default; set use_regex when enabled. Example: code_search(query=“TODO”, path_prefix=“src/”).
code_read
Section titled “code_read”Read a repository file by relative path, optionally sliced to a line range; end_line 0 means to the end. Returns sanitized text wrapped with provenance. Example: code_read(path=“src/app.py”, start_line=10, end_line=40).
symbol_map
Section titled “symbol_map”List the functions, classes, and types defined under a repository prefix, with their line spans. Example: symbol_map(path_prefix=“src/”).
dependency_graph
Section titled “dependency_graph”Map the imports between the Python modules under a repository prefix, marking dependencies outside it as external. Example: dependency_graph(path_prefix=“src/”).
assist
Section titled “assist”| Tool | Scope | Per minute | Hints |
|---|---|---|---|
code_explain |
assist:run |
10 | read-only, open-world |
summarize_diff |
assist:run |
10 | read-only, open-world |
rerank |
assist:run |
20 | read-only, open-world |
code_explain
Section titled “code_explain”Explain a repository file or line range through the configured model backend; end_line 0 means to the end. The explanation returns as untrusted data. Example: code_explain(path=“src/app.py”).
summarize_diff
Section titled “summarize_diff”Summarize a unified diff through the configured model backend; the summary returns as untrusted data. Example: summarize_diff(diff=“— a/x.py\n+++ b/x.py\n@@ …”).
rerank
Section titled “rerank”Rank candidate passages by relevance to a query through the configured model backend and return their indices in order. Example: rerank(query=“refund policy”, candidates=[“…”, “…”]).
| Tool | Scope | Per minute | Hints |
|---|---|---|---|
run_snippet |
exec:run |
10 | open-world |
run_tests |
exec:run |
4 | open-world |
run_snippet
Section titled “run_snippet”Run a short Python snippet in the sandbox and return its bounded, secret-redacted output. Requires the execution feature to be enabled and granted. Example: run_snippet(code=“print(2 + 2)”).
run_tests
Section titled “run_tests”Copy the authorized repository subtree into the sandbox and run the configured test command there, returning its bounded, secret-redacted output. Requires the execution feature to be enabled and granted. Example: run_tests(path_prefix=“src/”).
context
Section titled “context”| Tool | Scope | Per minute | Hints |
|---|---|---|---|
pack_context |
context:read |
10 | read-only |
workingset_get |
context:read |
60 | read-only |
workingset_update |
context:write |
30 |
pack_context
Section titled “pack_context”Assemble a token-budgeted context bundle for a query: a working set’s pinned items first, then retrieved snippets, each secret-scanned, provenance-stamped, and framed as untrusted data. Example: pack_context(query=“how are refunds issued?”, working_set=“refunds”).
workingset_get
Section titled “workingset_get”Read the contents of a named working set you own. A set you do not own is reported as not found. Example: workingset_get(name=“bug”).
workingset_update
Section titled “workingset_update”Pin, unpin, or clear references in a named working set. Each item is {“kind”: “doc”|“repo_file”, “identifier”: …, “note”: …}; pinned items are authorized as you pin them. Example: workingset_update(name=“bug”, action=“pin”, items=[{“kind”: “repo_file”, “identifier”: “src/app.py”}]).
| Tool | Scope | Per minute | Hints |
|---|---|---|---|
scan_corpus_async |
docs:scan |
10 | |
task_get |
tasks:read |
120 | read-only |
task_update |
tasks:write |
30 | idempotent |
task_list |
tasks:read |
60 | read-only |
task_schedule |
tasks:write |
10 |
scan_corpus_async
Section titled “scan_corpus_async”Start a background secrets-and-PII scan of the corpus (or a path prefix) and return a task handle immediately. Poll it with task_get(task_id=…) and cancel it with task_update(task_id=…, action=“cancel”). Example: scan_corpus_async(path_prefix=“exports/”).
task_get
Section titled “task_get”Return the status of a task you started, and its result once it has finished. A task id you do not own is reported as not found. Example: task_get(task_id=“3f2a…”).
task_update
Section titled “task_update”Update a task you started. The only action is “cancel”, which stops a running task. A task id you do not own is reported as not found. Example: task_update(task_id=“3f2a…”, action=“cancel”).
task_list
Section titled “task_list”List the task handles you own with their status and kind. Poll one with task_get(task_id=…). Example: task_list().
task_schedule
Section titled “task_schedule”Schedule a timer that completes after delay_seconds carrying your payload; repeat_seconds respawns the next occurrence. Poll with task_get(task_id=…); timers do not survive a restart. Example: task_schedule(delay_seconds=60, payload={“note”: “check build”}).
memory
Section titled “memory”| Tool | Scope | Per minute | Hints |
|---|---|---|---|
memory_store |
memory:write |
30 | idempotent |
memory_search |
memory:read |
60 | read-only |
memory_list |
memory:read |
60 | read-only |
memory_delete |
memory:write |
30 | destructive, idempotent |
kv_set |
memory:write |
60 | destructive, idempotent |
kv_get |
memory:read |
120 | read-only |
kv_delete |
memory:write |
60 | destructive, idempotent |
memory_store
Section titled “memory_store”Store a memory in a namespace you own and return its id. Identical content returns the existing id unchanged; pass id to update an entry in place. Example: memory_store(namespace=“prefs”, content=“prefers metric units”).
memory_search
Section titled “memory_search”Recall the memories in a namespace you own most relevant to a query. Recall is keyword on the file backend and semantic when an embedding provider is configured. Example: memory_search(namespace=“prefs”, query=“units”, k=5).
memory_list
Section titled “memory_list”List the ids and metadata of the memories in a namespace you own. Example: memory_list(namespace=“prefs”).
memory_delete
Section titled “memory_delete”Delete one memory you own by namespace and id. An id you do not own is reported as not found. Example: memory_delete(namespace=“prefs”, id=“3f2a…”).
kv_set
Section titled “kv_set”Set a scratchpad value for an exact key, replacing any prior value. ttl_seconds expires it; keys use letters, digits, and . _ : - only. Example: kv_set(key=“run:42:state”, value=“phase2”, ttl_seconds=600).
kv_get
Section titled “kv_get”Get the scratchpad value stored for an exact key you own. An expired or missing key is reported as not found. Example: kv_get(key=“run:42:state”).
kv_delete
Section titled “kv_delete”Delete the scratchpad value stored for an exact key you own. Example: kv_delete(key=“run:42:state”).
notify
Section titled “notify”| Tool | Scope | Per minute | Hints |
|---|---|---|---|
notify_webhook |
notify:send |
10 | open-world |
notify_webhook
Section titled “notify_webhook”POST a JSON payload to a webhook URL on the operator allowlist and return the bounded response status. Example: notify_webhook(url=“https://hooks.example.com/ci”, payload={“text”: “done”}).