Tools for assistants

People can connect an assistant to their site over MCP (Settings → Assistants), approving which areas it may view or change: content, structure, design, settings and people, code. Core offers tools for its own things; a module with tools = true adds its own, which assistants see as <module id>_<name> beside core's:

ctx.tools.register({
  name: "list_submissions",
  description: "Submissions to a form, newest first, with their answers.",
  area: "content",
  input: { properties: {
    form: { type: "string", description: "The form's slug." },
    email: { type: "string", personal: true },
  }, required: ["form"] },
  handler: list_submissions,
})?;

fn list_submissions(req) -> Result<Map, Error> {
  // req.args, req.user { id, name, email, roles, capabilities }, req.assistant { client, connection }
  let rows = ctx.db.find("submissions", { form: req.args.form })?;
  Ok({ submissions: rows, summary: "found " + str(len(rows)) })
}

area is one of content, structure, design, site, code. A tool appears only to assistants given that area, and one with write: true only to those allowed to change it.
A tool that changes anything (write: true) names a capability the person must hold (edit_pages, manage_members, …); req.user.capabilities is what the person lends the assistant, already narrowed to its areas.
input is a small JSON Schema: properties (each with a type of string, number, integer, boolean, array or object, and optionally description, enum, items, default) and required. Core checks the arguments before the handler runs. Mark arguments that hold someone's details personal: true, and keys or passwords secret: true: the audit log keeps them masked.
The handler gets { args, user, assistant } and answers a map (shown to the assistant; a summary key goes in the audit log) or Err(message), which the assistant sees as the tool's error. It has 30 seconds.
Every call is in the site's MCP audit log, and what the tool records with ctx.activity.record or changes through core says the assistant did it, through the module.
Describe the tool for an assistant: what it does, what it answers, and anything it changes that visitors see.

The forms module is a fuller example: listing and reading submissions, setting their status, exporting, and erasing a person's answers.

Modules