reply_email

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

Far exceeds what the annotations convey. It discloses recipient derivation ('original sender plus To/Cc minus your own address when reply_all is true'), subject mutation ('Re:' prefix if needed), threading header behavior (In-Reply-To and References), body quoting, and a confirmation requirement before sending. None of that is available from readOnlyHint=false / openWorldHint=true.

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 lead sentence is front-loaded and the Args block is scannable. The middle behavioral paragraph is a long compound sentence that packs several clauses together, but every clause carries information an agent needs, so it is dense rather than wasteful.

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?

A mutating, open-world tool with no output schema and seven parameters is fully covered: safety is handled by annotations, parameters are all explained, and side effects (threading, quoting, recipient set, confirmation) are disclosed. Nothing needed to call it correctly is missing.

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 0%, so the description must carry the full burden, and it does: the Args block documents all seven parameters, including the cross-reference for account ('from list_accounts') and the non-obvious behavior of body ('the quoted original is appended after it').

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 states a specific verb and resource ('Reply to a message') and immediately pins down the mode ('send the reply immediately'), which separates it from save_draft_email and, by construction of threading headers and quoting, from send_email and forward_email. An agent can identify the tool's role without opening the schema.

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 one explicit directive ('confirm with the user first'), which is genuine usage guidance for an irreversible send. However, it never states when to choose reply_email over save_draft_email, send_email, or forward_email, nor any prerequisites beyond the account/folder/uid inputs.

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