Agent tools
One catalogue of document tools serves every agent surface. The MCP server and the in-app assistant mount the same entries. Whichever surface calls, the capabilities, the RBAC, the caps, and the error mapping are the same.
For agents: Call tools with
tools/call— connect per MCP: connecting agents. Sequence:tools/list→whoami→get_schemabefore any write →list_documentswithfield__opfilters →create_document/update_document(JSON merge patch;nullremoves a key) →batch(25 ops max). A filter key the doctype does not declare raisesInvalidParams— never a silent empty result. Errors carrydata.reason; caps: 200 rows, 1 MiB envelope, 25 batch ops. Files move over HTTP:request_artifact_uploadmints a signed URL.
When to use this
Section titled “When to use this”Use this page when:
- You build an agent on the MCP surface, or you extend the assistant.
- You must know which tools exist, what they need, and what they return.
- A tool call fails, and you need the error contract.
Before you start
Section titled “Before you start”- Connect first — see MCP: connecting agents. This page speaks MCP; the assistant mounts the same entries.
- Call
whoamifirst: it returns the role, the permission lines, the scopes, and the visible tags. Fields whose tags fall outsidevisible_tagsare absent from every result.
The catalogue
Section titled “The catalogue”requires is the permission line the role must hold for the tool to appear
in tools/list:
| Tool | requires |
Purpose |
|---|---|---|
ping |
none | Server identity and the mounted role. |
list_domains |
read | Live domains; drafts excluded. |
list_doctypes |
read | Doctypes of one domain. |
get_schema |
read | Full doctype definition: fields, actions, scopes, member_of, sidecars. |
whoami |
none | Identity, permissions, scopes, visible tags. |
list_documents |
read | Filtered, sorted, paginated list. |
aggregate_documents |
read | count, or sum/avg/min/max over an integer, duration, or money field. |
get_document |
read | One document by id; optional expand and fields. |
create_document |
write | Full-content create; parent_id creates a child. |
update_document |
write | JSON merge patch (RFC 7386); null removes a key. |
delete_document |
write | Soft delete — a tombstone. |
batch |
write | Ordered atomic ops in one transaction. |
call_action |
action | Named doctype action with typed args. |
create_sidecar |
write | Sidecar create on a host document’s segment. |
list_sidecars |
read | One host’s sidecar segment, paged. |
list_mutations |
read | Document history — or the whole log, for a wildcard reader. |
resolve_refs |
read | A batch of URNs resolved to stub rows. |
get_links |
read | The outbound document links of one document. |
get_backrefs |
read | The live documents that link to one document. |
search_documents |
read | Cross-doctype search; 5 matches per doctype. |
request_artifact_upload |
write | A one-time signed upload URL for a file. |
get_artifact |
read | A short-lived signed download URL. |
list_artifact_refs |
read | The live documents that reference one artifact. |
read_skill is not a catalogue entry. Each surface mounts its own loader; the
MCP mount serves short markdown references for these tools.
1. List the tools and read the schema
Section titled “1. List the tools and read the schema”tools/list returns the role-filtered listing. Visibility is a convenience
for the agent, never a boundary: enforcement runs at call time, exactly as on
REST. Read get_schema before any write. It carries the fields, the actions,
the scopes, the member_of parent link, and the host’s sidecar segments.
2. List and read documents
Section titled “2. List and read documents”list_documents takes domain and doctype, plus:
| Argument | Purpose |
|---|---|
filters |
field__op keys — status__eq, salary__gte, name__match |
sort |
field names; a - prefix sorts descending |
page, items |
pagination |
fields |
project each row’s content to the named fields |
expand |
resolve reference fields into a resolved map |
scope |
apply a named row scope as a query-time filter |
parent_id |
list one parent’s children; child doctypes only |
Filter keys validate against the doctype. An unknown key, or an operator the
field does not serve, raises InvalidParams — never a silent empty result.
parent_id gates through the parent’s read scope, the same gate as the
nested REST route. An oversized result sets meta.truncated: true and
carries next_cursor; fetch that page next. Every row’s meta carries
display_name. aggregate_documents runs under the same filters and caps.
3. Write documents
Section titled “3. Write documents”create_document takes the full content. A child doctype needs parent_id; a
child without it is refused. update_document takes a JSON merge patch: new
keys are set, and a null value removes the key. delete_document
tombstones the document. batch runs ordered create, update, delete,
and action ops in one transaction; a failure rolls the batch back and names
the op index.
4. Act, extend, and inspect
Section titled “4. Act, extend, and inspect”call_action runs a named action with typed args. create_sidecar and
list_sidecars work on one segment of one host document. list_mutations
answers a document’s history; without a doc_id, it serves the whole log to
a wildcard reader. resolve_refs, get_links, and get_backrefs walk the
reference graph. search_documents fans a search term over every readable
doctype.
5. Move files over HTTP
Section titled “5. Move files over HTTP”No file bytes ride the tool channel:
- Call
request_artifact_upload. It returns a one-time signed upload URL. - POST the multipart
filepart to that URL. - Put the returned artifact id into a document.
- Call
get_artifactfor a download URL, orlist_artifact_refsto see where an artifact is used.
See Uploading and serving files for the HTTP side.
Caps and errors
Section titled “Caps and errors”The caps come from the mcp: block: 200 rows, 1 MiB envelope, 25 batch ops —
see MCP: connecting agents. An oversized result is cut,
not failed: it sets meta.truncated and next_cursor. Failures are JSON-RPC
errors:
| Error class | JSON-RPC code | Meaning |
|---|---|---|
InvalidParams |
-32602 |
Bad arguments; unknown argument keys are rejected centrally |
RbacDenied |
-32603 |
The role lacks the permission; it never names the failed line |
NotFound |
-32602 |
Unknown, tombstoned, and invisible documents give one non-disclosing answer |
Capped |
-32603 |
The result exceeds a cap |
ToolError |
-32603 |
Fallback |
Every failure carries a machine-readable data.reason:
data.reason |
Class | Extra keys |
|---|---|---|
invalid_params |
InvalidParams |
argument |
unknown_argument |
InvalidParams |
argument, tool |
unknown_field |
InvalidParams |
field |
unsupported_operator |
InvalidParams |
field, operator |
unknown_tool |
NotFound |
tool |
not_found |
NotFound |
deleted: true on a tombstone |
rbac_denied |
RbacDenied |
— |
capped |
Capped |
cap |
A validation failure on a write carries the per-field errors in data.details.
Example
Section titled “Example”The request:
{ "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_documents", "arguments": { "domain": "crm", "doctype": "Contact", "filters": { "status__eq": "active" }, "sort": ["-created_at"], "page": 1 } }}The payload rides in result.structuredContent; the same payload also rides as
a JSON string in result.content[0].text:
{ "data": [ { "data": { "name": "Ada Lovelace", "status": "active" }, "meta": { "id": "01JE2W4G7Q2M8X3K5P9R2T4V6W", "domain": "crm", "doc_type": "Contact", "mid": "01JE2W4G7Q2M8X3K5P9R2T4V6X", "version": 1, "created_at": "2026-11-13T09:12:44Z", "updated_at": "2026-11-13T09:12:44Z", "display_name": "Ada Lovelace" } } ], "meta": { "total": 1, "page": 1, "items": 1, "truncated": false, "next_cursor": null }}truncated: false with next_cursor: null is a final page. A page cut by
the row or byte cap sets truncated: true and next_cursor to the next
page number.
A create:
{ "jsonrpc": "2.0", "id": 8, "method": "tools/call", "params": { "name": "create_document", "arguments": { "domain": "crm", "doctype": "Contact", "content": { "name": "Grace Hopper", "email": "grace@example.com", "status": "active" } } }}The result carries the created content and the same meta shape, with a fresh
id and mid.
Troubleshooting
Section titled “Troubleshooting”The answer is unknown_argument.
A key no handler reads — check the tool’s inputSchema from tools/list.
A listed tool answers rbac_denied.
Listing is visibility; the role still gates the call. Check whoami for the
permission lines.
Results stop with truncated: true.
Fetch the page next_cursor names. The cut is a cap, not a failure.
NotFound for a document you can see elsewhere.
Row scope or non-disclosure. Check whoami; tombstoned and invisible
documents give the same answer.
Related
Section titled “Related”- MCP: connecting agents — the surface that serves this catalogue.
- Use the REST API — the same filters and errors over HTTP.
- Search — the corpus
search_documentsfans out over. - AI under the caller’s rights — the rights model.
- Internals on GitHub: agent-tools.md.