Found while writing content/docs/ai/tools.mdx (#10222). Out of that card's file surface, so filed rather than fixed there.
The defect
packages/spec/src/ai/agent.zod.ts carries agent.tools as a retiredKey() tombstone:
agent.tools was removed in @objectstack/spec 17 (#3894) — use skills. An agent reaches exactly the tools its surface-compatible skills declare (ADR-0064), so move each reference into a skill […] This is NOT a rename — there is no key the value moves to.
The tombstone types the key as never and rejects it at parse time. But content/docs/ai/agents.mdx still teaches it as a live authoring field, in two places:
- The "The shape of an agent" field table has a row:
tools — "Direct tool references{ type, name, description } — type is action | flow | query | vector_search; name points at an existing Action/Flow/query". - The
info callout directly under that table: "Agent tools are references to existing Actions, Flows, or queries — you do not define ad-hoc tool names with inline parameter schemas here."
Neither says the key is retired. A developer — or an AI author, which is the likelier reader here — following the table writes tools: [...] on a defineAgent(...) record and gets a compile error whose text is the tombstone prescription, with the docs still asserting the key is correct.
Why it matters beyond a stale row
The removal reason was a real capability leak: agent.tools[].name resolved against the full registry with no surface check, so an ask-surface agent could name an authoring tool and get it. ADR-0064's invariant is that an agent's tool set is exactly the union of its surface-compatible skills' tools, with no global fall-through. The documented row is the one shape that used to break that invariant.
Suggested fix
Replace the tools row and the callout with the retirement and its prescription — the same shape agents.mdx already uses correctly for the removed topics alias ("removed in protocol 17 (#3855)") and for the removed agent-level knowledge block in the Sales Assistant code comment.
Worth checking the same page's remaining field-table rows against AgentSchema in the same pass — this one was found incidentally, not by an audit.
Evidence
packages/spec/src/ai/agent.zod.ts — the tools: retiredKey(...) declaration and the docblock above it explaining why it is tombstoned rather than deleted (AgentSchema is not .strict(), so deletion would be a silent strip).content/docs/ai/agents.mdx — the "The shape of an agent" table and the callout beneath it.
Found while writing
content/docs/ai/tools.mdx(#10222). Out of that card's file surface, so filed rather than fixed there.The defect
packages/spec/src/ai/agent.zod.tscarriesagent.toolsas aretiredKey()tombstone:The tombstone types the key as
neverand rejects it at parse time. Butcontent/docs/ai/agents.mdxstill teaches it as a live authoring field, in two places:tools— "Direct tool references{ type, name, description }—typeisaction|flow|query|vector_search;namepoints at an existing Action/Flow/query".infocallout directly under that table: "Agent tools are references to existing Actions, Flows, or queries — you do not define ad-hoc tool names with inline parameter schemas here."Neither says the key is retired. A developer — or an AI author, which is the likelier reader here — following the table writes
tools: [...]on adefineAgent(...)record and gets a compile error whose text is the tombstone prescription, with the docs still asserting the key is correct.Why it matters beyond a stale row
The removal reason was a real capability leak:
agent.tools[].nameresolved against the full registry with no surface check, so anask-surface agent could name an authoring tool and get it. ADR-0064's invariant is that an agent's tool set is exactly the union of its surface-compatible skills' tools, with no global fall-through. The documented row is the one shape that used to break that invariant.Suggested fix
Replace the
toolsrow and the callout with the retirement and its prescription — the same shapeagents.mdxalready uses correctly for the removedtopicsalias ("removed in protocol 17 (#3855)") and for the removed agent-levelknowledgeblock in the Sales Assistant code comment.Worth checking the same page's remaining field-table rows against
AgentSchemain the same pass — this one was found incidentally, not by an audit.Evidence
packages/spec/src/ai/agent.zod.ts— thetools: retiredKey(...)declaration and the docblock above it explaining why it is tombstoned rather than deleted (AgentSchemais not.strict(), so deletion would be a silent strip).content/docs/ai/agents.mdx— the "The shape of an agent" table and the callout beneath it.