mailbox_send_draft

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

Annotations only flag idempotentHint and destructiveHint, but the description goes much further: the approval-fallback flow, the fact that sending cannot be undone, that a submitted draft can no longer be edited, and that repeating the same id+revision returns the existing send status instead of re-sending. It even explains that 'queued is not delivered' and where to check the real outcome.

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?

It is dense and slightly long, but front-loaded with the core action and every clause carries information (permission branch, irreversibility, idempotency, status values, next step). No filler sentences, though the status enumeration could be trimmed.

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?

There is no output schema, and the description compensates by enumerating the possible send statuses (queued, sending, accepted, unknown, failed) and pointing to the draft/Sent folder for the delivery outcome. Combined with the approval flow and idempotency guarantees, an agent has everything needed to invoke and interpret this tool.

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 coverage is 100%, so the schema already documents id, mailbox and expected_revision, making 3 the baseline. The description adds genuine meaning by framing expected_revision as an optimistic-concurrency pin ('exactly as it is at the given revision') and by explaining that id+revision together form the idempotency key.

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 precise verb+resource: sending an already-saved draft pinned to a revision. It clearly distinguishes this from sending a new message by tying it to drafts produced by mailbox_save_draft or mailbox_list_messages, so an agent can tell it apart from send_email/send_email_batch.

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 clear conditioning: with the send permission it goes out immediately, otherwise it becomes an approval request and the owner is emailed. It also tells the agent what to do on repeat calls. It never explicitly contrasts with send_email or send_email_batch, so the alternatives routing is implied rather than stated.

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