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

Annotations only indicate non-read-only, non-destructive, non-idempotent behavior. The description goes far beyond that by disclosing rejection criteria, the 30MB upload limit, US Letter output, the reserved address zone that pushes content to additional pages, estimatedPageCount being only a baseline, and the server-side substitution and rendering behavior. This gives the agent a thorough understanding of side effects and constraints.

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 carries essential information: use case, examples, alternatives, constraints, limitations, return values, and integration with create_mail_quote. It is well-structured into logical paragraphs and front-loads the most critical decision (when to use) before details.

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?

With no output schema and limited annotations, the description carries the full burden of explaining return values and workflow. It clearly states that the response includes a documentId with kind 'html_template', a mergeFields list, and estimatedPageCount, and it explains how those values relate to subsequent per-recipient quoting. Coverage of error conditions, size limits, page size, and reserved address zones makes this tool fully understandable.

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 already covers all 5 parameters with descriptions, but the description adds substantial value: exactly one source must be provided, the format can be inferred, and the maximum size is 30MB. However, there is a conflict: the description calls `contentBase64` 'base64-encoded text' while the schema says it is 'Base64-encoded binary content (pdf, docx, image)', which could mislead an agent. This inconsistency prevents a perfect score.

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 a specific action ('Upload a REUSABLE template') and clearly distinguishes this tool from siblings by explaining that it is for mail-merge content with `{{field}}` placeholders. It explicitly contrasts with create_letter and create_mail_quote, so the agent can select it unambiguously.

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 explicit when-to-use guidance: only when content varies per recipient, and tells the agent to use create_letter for identical content. It also explains exactly how to invoke the tool once per recipient with create_mail_quote, enumerates the exactly-one-source rule, and warns about rejection for missing `{{fields}}`.

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