Skip to content

Agent tools

Generated from src/agent_tools/ by make 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: links in longtext. 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.