Send from a template

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

Beyond the annotations it discloses the real external side effect (immediate e-mail to recipients with delivery EMAIL), the safe draft mode, and the retry contract via externalRef/idempotencyKey. That is meaningful added context for an openWorldHint=true tool. Minor tension: the description promises safe retry while idempotentHint=false, which is explainable (idempotency is caller-supplied, not automatic) but could be spelled out more crisply.

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?

Four tight sentences, front-loaded with what the tool creates, followed by the send=true/send=false branch and then the retry note. No filler or repetition of the schema, though the final idempotency sentence is the least essential of the four.

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 an 8-parameter nested tool with no output schema, the definition covers the create-and-send flow, the draft path, the confirmation requirement, and retry semantics. The main remaining gap is that it never says what comes back (document id? status?) nor points at list_templates for obtaining templateId and role keys, forcing the agent to infer both.

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 only 50% schema coverage, the description compensates well: it explains that roles maps one person per role key, that data supplies values for template data keys, and that delivery EMAIL gates the e-mail behavior. externalRef and idempotencyKey also get purpose-level meaning. title, message, and language remain undocumented in prose, keeping it off a 5.

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 opening clause gives a concrete verb and resource ('Creates a document from a template') plus the shape of the two main inputs (one person per role, values for data keys). It is clear against most siblings, though it never explicitly distinguishes itself from send_document or send_draft, which an agent could plausibly confuse for the same outcome.

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 gives explicit branching guidance: send=true e-mails recipients with delivery EMAIL, send=false produces a console-reviewable draft, and it adds the precondition 'confirm the people and values with the user first' before sending. What is missing is routing against sibling alternatives such as send_draft or send_document when a document already exists.

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