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

The description goes far beyond the minimal annotations by disclosing that this writes directly (not through Inbox), is a derived AI summary (not design truth), is easily reversible by the owner, and automatically stamps the project version. It also specifies content constraints (only facts, no invented numbers, describe never evaluate, dominant language) and structural rules, giving the agent a clear behavioral model.

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 long but every sentence earns its place. It is well-structured with bold labels, a code block for the outline, and clear grouping of rules and constraints. The main purpose is front-loaded, and the level of detail is justified by the complexity of the tool.

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 write tool with no output schema and only destructiveHint=false, the description is remarkably complete. It covers the action, the direct-write behavior, prerequisites, formatting, word count, language, evaluation policy, and even version stamping. There is no significant missing behavioral or usage information that the agent would need.

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?

The schema covers only 50% of parameters (summary has a description; project_id does not). The description compensates by detailing the exact markdown structure and word count for `summary`, and it implies `project_id` through phrases like 'the project version.' It does not explicitly define `project_id`, but the overall context makes its purpose clear, so the added value is strong but not perfect.

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?

The description clearly states the action ('Write') and the resource ('the Design Document's Overview'), and differentiates it from sibling tools by emphasizing 'WRITES DIRECTLY (no Inbox)' — distinguishing it from propose_* tools. It also specifies the exact purpose ('human-readable page a new team member reads first') and even names a prerequisite tool (get_design_document).

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?

It provides explicit context: this is for writing the design overview, and it mandates a precondition ('call get_design_document with for_summary:true first'). It also states 'HARD RULES, same as the in-app button,' which signals consistency with an existing workflow. However, it does not explicitly contrast with alternative write/update tools beyond the no-Inbox note, so it stops short of a full when-to-use versus when-not-to-use guide.

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