From 888aebf68265ecc1848b24a9e3fa7983da37da89 Mon Sep 17 00:00:00 2001 From: "claude[bot]" Date: Fri, 21 Aug 2026 09:34:10 +0000 Subject: [PATCH] docs(ai): mark retired agent.tools as removed in agents.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The field table and the callout under it still taught `agent.tools` as a live authoring field, while `packages/spec/src/ai/agent.zod.ts` carries it as a `retiredKey()` tombstone — typed `never`, rejected at parse. The page already stated the correct ADR-0064 rule in its own prose, so it contradicted itself. Replace the row with the retirement and its prescription, and rewrite the callout to state the ADR-0064 invariant and why the key is gone: the runtime resolved the reference against the full registry with no surface check. Not a rename — no migration command is offered, because there is no key the value moves to. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- content/docs/ai/agents.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx index 491a66adbf..c4219cdecb 100644 --- a/content/docs/ai/agents.mdx +++ b/content/docs/ai/agents.mdx @@ -207,7 +207,7 @@ own `ask` / `build` records use exactly these fields): | `instructions` | System prompt / prime directives | | `model` | Provider + model config (`provider`: `openai` \| `azure_openai` \| `anthropic` \| `local`) | | `skills` | Skill names to attach (the primary Agent → Skill → Tool capability model) | -| `tools` | Direct tool **references** `{ type, name, description }` — `type` is `action` \| `flow` \| `query` \| `vector_search`; `name` points at an existing Action/Flow/query | +| `tools` | **Removed in protocol 17 (#3894)** — typed `never`, so writing it fails `tsc`, and a value that reaches the runtime is rejected at parse. This is **not** a rename: there is no key the value moves to. Declare each tool on a **skill** instead — a platform tool by its registered name, or `action_` for one of your own AI-exposed Actions — and attach that skill through `skills` (ADR-0064) | | `knowledge` | RAG access: `{ sources: string[], indexes: string[] }`. `sources` is the only key; the `topics` alias was removed in protocol 17 (#3855) — `os migrate meta --from 16` rewrites it | There is no `type` field and no fixed agent "type" taxonomy — behaviour comes from @@ -217,9 +217,15 @@ the **ObjectOS** runtime — via the in-product chat endpoint (`/api/v1/ai/*`). On the open-source framework, invoke the underlying Actions/Flows through `@objectstack/mcp`. - -Agent tools are **references** to existing Actions, Flows, or queries — you do -not define ad-hoc tool names with inline parameter schemas here. See + +**An agent has no tool slot of its own.** Its tool set is exactly the union of +its surface-compatible skills' tools, with no fall-through to the global +registry ([ADR-0064](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0064-tool-scoping-to-agent.md)). +The removed `tools` key was the one seam that broke that invariant: the runtime +resolved `agent.tools[].name` against the **full** registry with no surface +check, so an `ask`-surface agent could name an authoring tool and reach it. So +there is nowhere on the agent to move a reference **to** — re-declare each one +in a skill's `tools` by hand, then attach the skill. See [Actions as Tools](/docs/ai/actions-as-tools) for how an Action becomes LLM-callable.