Agent tools
Generated from
src/agent_tools/bymake gen-docs-agent-tools. Do not edit this file by hand.
Use this page to look up a tool, its access class, and its parameters.
Facet exposes one catalogue of document tools to every agent surface. The
MCP resource server lists the whole catalogue under tools/list; the
in-process assistants mount the subset they need. The registry holds
23 tools. Visibility filters the list per role; enforcement
always runs at call time, exactly as on REST.
The Access column is the tool’s requires tag from the registry. A role
sees a tool when its permission map clears the class:
read— at least one read line.write— at least one create, update, or delete line.action— a named action or the*wildcard.none— always visible to a signed-in principal.
| Tool | Access | Purpose | Parameters |
|---|---|---|---|
aggregate_documents |
read | Aggregate documents of one doctype with the same filter grammar as list_documents. | aggregate (string, required) doctype (string, required) domain (string, required) field (string, optional) filters (object, optional) parent_id (string, optional) scope (string, optional) |
batch |
write | Apply an ordered list of writes atomically — all land or nothing does. | ops (array, required) |
call_action |
action | Execute a named action on one document. | action (string, required) args (object, optional) doc_id (string, required) doctype (string, required) domain (string, required) |
create_document |
write | Create one document of the given doctype. | content (object, required) doctype (string, required) domain (string, required) parent_id (string, optional) |
create_sidecar |
write | Create one sidecar record attached to a host document — the host-scoped nested-sidecar create (REST: POST /Api/:domain/:doctype/:id/:segment), generic over every sidecar doctype (comments, attachments, …). | content (object, required) doc_id (string, required) doctype (string, required) domain (string, required) segment (string, required) |
delete_document |
write | Soft-delete one document (tombstone, recoverable through audit replay). | doc_id (string, required) doctype (string, required) domain (string, required) |
get_artifact |
read | Mint a short-lived signed download URL for one artifact. | artifact_id (string, required) |
get_backrefs |
read | Find the live documents that point at one document — the inverse of get_links. | doc_id (string, required) doctype (string, required) domain (string, required) |
get_document |
read | Read one document by id. | doc_id (string, required) doctype (string, required) domain (string, required) expand (array, optional) fields (array, optional) |
get_links |
read | Get the outbound links of one document — the urn:facet:… references this document points to (from its reference fields and inline longtext links). | doc_id (string, required) doctype (string, required) domain (string, required) |
get_schema |
read | Get the full schema of one doctype: fields (types, required, constraints), named actions with their typed arguments, child doctypes, the parent doctype (member_of, on a child), sidecar segments (host-scoped record types attached through the nested routes — e.g. comments or attachments, via create_sidecar/list_sidecars), and named scopes. | doctype (string, required) domain (string, required) |
list_artifact_refs |
read | List the live documents that currently reference one artifact — both ‘file’ field placements and inline urn:facet:artifact: |
artifact_id (string, required) |
list_doctypes |
read | List the document types of one domain. | domain (string, required) |
list_documents |
read | List documents of one doctype. | doctype (string, required) domain (string, required) expand (array, optional) fields (array, optional) filters (object, optional) items (integer, optional) page (integer, optional) parent_id (string, optional) scope (string, optional) sort (array, optional) |
list_domains |
read | List the live domains (bounded contexts) available in Facet. | — |
list_mutations |
read | List the mutation history of one document, or — with no doc_id — the recent mutations of the whole workspace (domain/doctype narrow as filters; needs the wildcard read grant). | doc_id (string, optional) doctype (string, optional) domain (string, optional) filters (object, optional) items (integer, optional) page (integer, optional) sort (array, optional) |
list_sidecars |
read | List the sidecar records of one segment attached to a host document — the host-scoped nested-sidecar list (REST: GET /Api/:domain/:doctype/:id/:segment), generic over every sidecar doctype. | doc_id (string, required) doctype (string, required) domain (string, required) items (integer, optional) page (integer, optional) segment (string, required) |
ping |
none | Health probe. | — |
request_artifact_upload |
write | Get a one-time signed upload URL for a file artifact. | filename (string, required) size_bytes (integer, optional) |
resolve_refs |
read | Resolve a batch of document URNs (urn:facet:domain:Doctype:id — the inline links of longtext fields, links entries, or reference values) to documents in one call. | fields (array, optional) refs (array, required) |
search_documents |
read | Search every readable doctype at once — use it when you do not know where a document lives. | domain (string, optional) items (integer, optional) query (string, required) |
update_document |
write | Partially update one document. | doc_id (string, required) doctype (string, required) domain (string, required) patch (object, required) |
whoami |
none | Read your own identity and access: the account you act as, the mounted role, its permission manifest (doctype -> actions and scope aliases), and the role’s visible tags. | — |
One tool is not a registry entry: read_skill, the skill loader. The MCP
surface appends it to tools/list, and the workspace assistant mounts its
own. Both take one required argument, name (string). It serves the shared
skill corpus in src/agent_tools/skills/, filtered by the surfaces
front-matter of each skill file.