Conciseness

The body is dense and efficient: tables replace prose, code is unannotated, and gotchas are symptom-lead bullets with no explanation of concepts Claude already knows. The one trim opportunity is the ToolCallMessagePartProps field table, which largely duplicates the renderer-props table in ./references/tool-ui.md — a minor instance that could be delegated.

Actionability

The four-step authoring model provides copy-paste-ready code for every step (next.config.ts with withAui, a complete defineToolkit entry, AuiConfig/Tools mounting, and the AISDKToolkit route handler) with exact imports and package names, and each gotcha pairs a symptom with a concrete fix. Examples are fully executable and cover the common cases.

Workflow Clarity

The setup is sequenced 1-4 with each step's purpose stated ('The directive does nothing without a compiler'), validation is explicit at build time ('The compiler enforces at build time that every tool declares an execute...'), and the Common Gotchas section is a symptom -> diagnosis -> fix feedback loop (e.g. a runtime humanTool() throw means the file was never compiled, so add the build plugin).

Progressive Disclosure

Eight references, each annotated with exactly what it contains, all real files in ./references/, one level deep; deep material (MCP servers, MCP Apps, WebMCP, multi-agent, legacy APIs) is kept out of the body with the core patterns inline and clear delegation ('the full option, question, and resolution surface is in human-in-loop.md'). A Related Skills section aids cross-navigation.

Specificity

The description enumerates concrete actions and real API surface ('Defines model-callable tools and renders their calls in assistant-ui', 'defineToolkit({...})', 'compiled by withAui', 'mounted with AuiConfig({ tools: Tools({ toolkit }) })') plus the full kind and feature list (humanTool(), providerTool(), approval gates, MCP Apps, WebMCP, sub-agent messages). Coverage is comprehensive with no vague or generic clauses.

Completeness

Both questions are explicitly answered: the 'what' is a full authoring model plus covered surface, and the 'when' is an explicit 'Reach for it when...' clause enumerating five concrete triggers. This matches the anchor example's what+when pattern exactly.

Trigger Term Quality

'Reach for it when a tool is never called, a tool UI does not render, a frontend result never reaches the model, humanTool() throws at runtime, or an approval gate cannot be answered' matches the natural failure phrases a user in this domain would actually say, complemented by kind vocabulary (backend/frontend/human tool/approval gates/MCP/WebMCP). No meaningful natural trigger phrasing is missing for this niche.

Distinctiveness Conflict Risk

The niche (model-callable tools in assistant-ui) is distinct, and the closing sentence actively routes adjacent needs elsewhere ('For model-composed UI use generative-ui, for MCP servers users add in the browser use react-mcp, and for the styled ToolFallback and ToolGroup use elements'), minimizing wrong-skill triggering.