build_doc

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and it delivers: it details side effects (freezing artboards to .build/snapshot/, creating versions/<n>/, re-rendering preview.html), prerequisites (doc.md written, screenshots sealed), the constraint that note is required and must not include a version number, and that error-level findings block publication at record_publish. This exceeds what the schema or annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence carries operational value — mode semantics, prerequisites, side effects, output semantics. It is front-loaded with the core purpose ('构建文档版本，两阶段'), though the single-paragraph wall of text would benefit from bullet separation for the two modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with no output schema, the description covers inputs, workflow, prerequisites, side effects, return url, and downstream gating by record_publish. It does not fully specify what 'checks' run or what label/author mean, but overall the agent has enough context to invoke both modes correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 29% (dir and projectId documented). The description compensates substantially for mode, explaining both enum values in detail, and for note, adding the requiredness, single-sentence rule, and purpose in the modification table. docId's meaning is implied through file paths. However, label and author receive no explanation in either schema or description, so it does not fully compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with '构建文档版本，两阶段' (build document version, two stages) — a specific verb+resource+process. It names the two modes, snapshot and finalize, and references the sibling tools build_publish_pack and record_publish, situating build_doc in the workflow. This lets an agent distinguish it from create_doc or export_doc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when each mode applies: snapshot only for doc types needing canvas screenshots, finalize after doc.md is hand-written and screenshots sealed, and pure prose changes can finalize directly reusing .build/ artifacts. It does not explicitly list alternative tools to choose instead, but the mode-level workflow is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.