docs(ai): `tool` metadata has a reference and no guide — and the guide has to say when NOT to author one (ADR-0109)

[os-elon]

Part of #10206

Notation note (2026-08-20): the materialised-tool name is written action_{name} below, in braces. GitHub's body sanitizer on this repo eats angle-bracket-delimited text and silently ate it from this card when it was first filed — three places, including inside a verbatim quote of the spec's own describe string, which read action_ tools. Corrected and read back. The real spelling in the source uses angle brackets; take it from the source, not from this card.

The gap

tool is a metadata kind (ToolSchema), authorable as defineStack({ tools }). The AI section covers agents (ai/agents.mdx), skills (ai/skills.mdx, ai/skills-reference.mdx), RAG, MCP and NL queries — but nothing covers authoring a tool record. ai/actions-as-tools.mdx is about the automatic path: an action materialising as an action_{name} tool.

Why this card needs care

The stack describe string is unusually opinionated, and it is the spine of the page (quoted with the brace substitution noted above):

'AI Tool metadata records — optional refinement layer, never required: the default path is skills referencing platform tools or materialised action_{name} tools (ADR-0109)'

So the guide's job is not to encourage authoring tools. It is to tell a developer that the default path is skills + materialised action tools, and that a tool record is a refinement layer they reach for only in specific circumstances. A page that reads as "here is how to add a tool" would push readers off the intended path — that is the failure mode to avoid, and it is why this is not a five-minute card.

Related: ADR-0063 §2 makes agent platform-internal (the kernel ships exactly two, ask/build; third parties extend via skills, not agents). ai/agents.mdx should already say this — verify that it does, and if it does not, report it rather than fixing it here.

File surface

• content/docs/ai/tools.mdx — new
• content/docs/ai/index.mdx — edit (Cards + the sentence placing tools relative to skills)
• content/docs/ai/meta.json — one added entry

⛔ Nothing outside content/docs/ai/. Do not edit actions-as-tools.mdx or skills.mdx — cross-link them.

What to write

Read ToolSchema (packages/spec/src/ai/tool.zod.ts), ADR-0109, and the tools: docblock in stack.zod.ts:

• Open with the decision, not the shape: the three ways a capability becomes available to an agent — a platform tool referenced by a skill, an action materialised as action_{name}, and an authored tool record — and when each is right. A reader who leaves after this section should already be on the correct path.
• What a tool record can refine that the materialised path cannot.
• The declaration shape, with one worked example.
• How a skill or agent references it by name.
• Cross-links: skills.mdx for the extension primitive, actions-as-tools.mdx for the default path, connect-mcp.mdx for external tools.

⛔ Non-goals

• Do not present authoring a tool as the normal way to extend the AI surface.
• Do not touch packages/spec/**.
• If ToolSchema carries properties nothing reads, that is an ADR-0049 finding for the domain:spec seat — report it, do not document it.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff; ADR anchor checks apply once you cite ADR-0109 / ADR-0063 decision letters.

⚠️ Adding a hand-written page turns check:docs-audit-scope RED until you run node scripts/docs-audit/check-audit-scope.mjs --write, which writes one line into .claude/workflows/docs-accuracy-audit.js. That is expected and required (see #9866). Commit exactly what --write produces, name it as a declared deviation in the PR body, and do not flip the PR ready or enqueue it — .claude/** is a governed surface, so the PR is human-merge-only.

Acceptance

• A developer wondering "how do I give my agent a new tool" is routed to skills / materialised action tools first, and reaches a tool record only when it is the right answer.
• Named gates green.

[os-elon]

Claim: PM loop round 3 (epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10222-tool-metadata
Worktree: objectstack-issue-10222
Domain: domain:devx
File surface: content/docs/ai/tools.mdx (new), ai/index.mdx, ai/meta.json, plus .claude/workflows/docs-accuracy-audit.js (the --write regeneration — declared) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived mandate; tier is this seat's call. Held at the judgment tier because the card's whole risk is tone: a page that reads as "here is how to add a tool" pushes readers off the path ADR-0109 designates as default.
Clause-②: no — documentation only.
Serial constraints cleared: content/docs/ai/** — no in-flight claim, no open PR. Batch-3 sibling #10218 owns content/docs/getting-started/**; disjoint.

⚠️ Body correction on this card: action_<name> was silently truncated to action_ by GitHub's sanitizer when the card was filed — three places, including inside a verbatim quote of the spec's describe string. The body now uses action_{name} brace notation and has been read back. Read the current body, and take the real spelling from the source.

---

Generated by Claude Code