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

Annotations declare readOnlyHint=true and idempotentHint=true, and the description reinforces and enriches this by stating it 'renders exactly what was already resolved and stored' and never re-runs reasoning or re-matches archives. It also discloses the failure behavior for base64 delivery (fails closed with a repair instruction) and the 'nothing is invented' rule for blank fields, adding significant behavioral context well beyond what annotations provide.

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 a single dense paragraph that front-loads the core action, use case, and constraints before detailing output structure. Every sentence carries substantive information, but the lengthy enumeration of DOCX and XLSX layouts could be trimmed or restructured for even faster scanning. Still, for a tool with this complexity, it is appropriately detailed and mostly efficient.

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?

The description covers identifier exclusivity and ownership rules, the exact content structure for both formats, delivery modes with fallback behavior, and the no-invention guarantee. An output schema exists, so the description appropriately avoids repeating return values. This is fully sufficient for an agent to select and invoke the tool 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?

With 100% schema coverage, the baseline is 3, but the description adds critical semantics: 'Accepts exactly one of house, house_ref, or project_id' and explains ownership/resolution rules. It also clarifies the delivery enum's default and fallback behavior, and that project_version targets a specific immutable version. These details go beyond the schema descriptions, improving parameter understanding and correct usage.

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 opens with 'Export the same house-flagship content palette_pdf renders as a genuinely editable Word document or Excel workbook', naming the specific verb, resource, and target formats. It distinguishes from sibling palette_pdf by explicitly targeting editable DOCX/XLSX rather than a PDF render, making the tool's unique purpose unmistakable.

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?

The description provides clear use cases ('for a client who needs to annotate the scheme, or a contractor building a materials/procurement schedule') and clarifies when it should not trigger re-reasoning ('Never calls house_specify, never re-runs reasoning or re-matches archives'). It also gives fallback guidance via the OUTPUT_TOO_LARGE_FOR_INLINE_DELIVERY error. However, it does not explicitly name alternative export tools for other scenarios, so it stops short of a fully explicit when/not-to-use matrix.

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