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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real value on top by spelling out the consequences ('This cannot be undone', recipients receive the message and its attachments, can read it, and become thread participants). 'Cannot be undone' is consistent with destructiveHint and with idempotency (re-adding the same addresses is a no-op). Permission details beyond the eligibility rule are not covered.

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?

Three tight sentences with zero filler. The core action and its scope come first, the side effects second, and the irreversibility/failure caveats last, which is the right front-loading for a destructive operation.

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?

An output schema exists, so return values need not be described. Together with annotations, the description covers action, eligibility, side effects, irreversibility, and failure mode. It is largely complete, though it says nothing about how already-participating recipients are handled.

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 100%, so the schema already documents id, recipients, and the deprecated add_to alias, including the 'pass one or the other' constraint. The description only echoes the sent-message targeting implied by id; baseline 3 applies.

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?

States a specific verb and resource ('Add recipients to a message that was already sent') and scopes it to messages the caller sent or received as a primary recipient. Clearly distinguishable from send_message, reply, and create_draft, which deal with unsent or new messages.

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?

Gives an explicit eligibility precondition (message already sent, caller was sender or primary recipient) and a failure condition ('Fails on terminal messages'), which tells the agent when not to bother. It does not name a sibling alternative (e.g., use reply instead when composing a new response), so it falls just short of full routing guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description is free to add real context: the draft is visible in the user's other fmsg clients, nothing is transmitted until send_draft, and secrets in the body and topic are redacted. Those are non-obvious side effects and data-handling traits that go beyond the annotations; only the non-idempotent behavior is left to the hint.

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?

Three dense sentences, front-loaded with the core action, then lifecycle, then the redaction caveat. No filler and no repetition of schema content.

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 output schema means return values need no explanation, and the description covers the draft lifecycle, cross-client visibility, and redaction. The one thing an agent might still want is confirmation of the required body versus optional addressing, but the schema carries that cleanly.

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 100%, so the schema already explains every parameter, including the to/reply-all interaction and the topic/reply_to conflict. The description adds sentiment about reply rules applying but no syntax or format detail beyond the schema; baseline 3 is appropriate.

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?

States a specific verb and resource ('Create an unsent draft') and immediately disambiguates the two modes: a new message, or a reply when reply_to is given. It is clearly separable from siblings like send_draft, reply, and send_message.

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?

Explicitly frames the draft as a staging step ('Nothing is sent until send_draft') and names delete_draft as the discard path, which gives clear context for when to reach for this tool. It stops short of an explicit when-not or a direct comparison against the sibling reply tool, which also produces replies.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that by disclosing that attachments are deleted along with the draft and by scoping the operation to unsent content.

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?

Two short sentences, no filler, with the primary action and its scope side-effect (attachments) leading. Every clause earns its place.

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 a one-parameter destructive mutation with a full annotation set and an output schema, the definition is largely sufficient. It omits any note on required permissions or whether the deletion is recoverable, which would be the remaining behavioral gaps given the annotations already cover safety and idempotency.

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?

There is a single parameter with 100% schema description coverage ("the draft to delete"), so the schema already carries the meaning. The description adds no format, ID-source, or lookup guidance, leaving this at the baseline.

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?

States a specific verb and resource ("Delete an unsent draft") and immediately bounds the target with "and its attachments." The restriction "Sent messages cannot be deleted" implicitly separates this from any message-level operation, though no sibling tool is named explicitly.

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?

Gives a clear condition for use (unsent drafts) and a clear exclusion (sent messages). It doesn't point to an alternative route for removing sent content, but no sibling tool offers that, so the guidance is effectively complete.

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

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

Beyond the readOnly/idempotent annotations, the description discloses materially useful behavior: delivery is asynchronous, pending recipients may still be delivered, temporary failures are retried, and it decodes response codes (200 accepted, 100 user unknown as rejection). This is exactly the context an agent needs to interpret results correctly.

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 purpose is front-loaded and every subsequent sentence adds value (scenario semantics, response-code meaning, async caveat). It is dense but no sentence is filler.

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 an output schema present the description needn't enumerate return values, and it already explains entry contents (delivered time, response code). It is essentially complete, missing only explicit alternative-routing guidance.

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 100% and the single id parameter is documented as 'fmsg message id', so the schema carries the load. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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 - the per-recipient delivery state of a message - and explicitly scopes it apart from content-retrieval siblings like get_message. An agent can immediately tell this tool is about delivery outcomes, not message bodies.

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 frames the two relevant scenarios (a message you sent vs a received message), which implies when the tool applies, but it never names an alternative or a when-not condition. The guidance is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds genuinely new context: the exact transformation applied per content type and the security caveat that attachments are untrusted third-party data, which an agent should weigh before echoing content downstream.

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?

Two sentences, front-loaded with the action and format behavior, followed by a short security note. No filler, no repetition of the name or title.

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 annotations covering safety and an output schema covering the return shape, the description is nearly sufficient. It stops short of saying what happens on failure (attachment missing, size refusal) even though that behavior is partly encoded in the max_inline_bytes schema description.

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 100%, so the schema already documents id, filename and max_inline_bytes (including the refusal threshold semantics). The description only alludes to size indirectly via 'small attachment' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

Specific verb (Download) plus resource (attachment), and it further specifies the rendering by content type: quoted text for text, image block for images, base64 resource for other files. No sibling tool does anything similar, so an 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 word 'small' and the inline framing imply this is for modest attachments rather than bulk retrieval, but there is no explicit when-to-use/when-not-to-use guidance and no named alternative for large files or for listing attachments on a message. Usage is inferable only from context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-derivable behavior: fetching does NOT mark the message read, non-text bodies are summarized rather than returned, and body text is untrusted quoted data (an injection warning). These are real behavioral facts an agent cannot infer from the schema or annotations.

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?

Three sentences, no filler, return surface front-loaded before the two routing sentences. Every sentence carries distinct information.

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?

An output schema exists, so return values need not be explained, yet the description still summarizes the shape usefully. Combined with the read-state and attachment caveats, an agent has everything needed to call this 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?

Schema description coverage is 100%, so both id and max_body_bytes (including the truncation semantics) are already documented in the schema. The description's 'full body' phrasing arguably conflicts mildly with the truncation default, but adds no parameter detail beyond the schema. Baseline 3 applies.

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?

States a specific verb (Fetch) and resource (one message) and enumerates the returned surface: body, headers, recipients, added recipients, delivery state, reactions, attachment list. It also names sibling tools (download_attachment, mark_read) so the agent can separate this from adjacent operations.

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?

Explicit routing in both directions: files go to download_attachment, and read-state changes go to mark_read. The condition selecting each alternative is stated, not implied.

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

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

Adds substantial context beyond the annotations (which already cover read-only/idempotent/safe): messages the caller cannot see appear as gaps, and the result pre-computes the reply target and reply-all participant set for the reply tool. It also carries an explicit prompt-injection guardrail, telling the agent to treat participant words as data, not instructions.

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?

Front-loads the core behavior, then layers scope, edge cases, a safety note, and downstream benefit in short, dense sentences with no filler. Every sentence conveys distinct information an agent needs.

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?

An output schema exists, yet the description still sketches the return shape (sender, time, recipients, flags, body) and explains gap/truncation behavior. Combined with annotations and full schema coverage, an agent has everything needed to call and interpret this 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?

Schema description coverage is 100%, so the schema already documents all four parameters including the truncation and omission semantics. The description adds little parameter-level detail beyond confirming that the id may be 'any message in the thread,' which is a marginal restatement of the schema. Baseline 3 applies.

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?

States a specific verb and resource ('Reconstruct the direct lineage of a message') and immediately scopes what is returned: root, each parent, and the given message. It distinguishes itself from siblings by naming the tools that cover the excluded other branches.

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?

Explicitly states what is out of scope ('Other replies in the thread (other branches) may exist and are not included') and routes the agent to list_messages and list_sent for that content. It also explains an edge case for usage: invisible messages surface as gaps, so the agent knows how to interpret results.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses non-obvious behavior: reactions are hidden by default, hidden reactions never count as unread, listed reactions carry their own read state and are accepted by mark_read, and thread topics live only on a thread's first message. This is exactly the operational nuance annotations cannot express.

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?

Front-loaded with purpose and ordering, then behavior, then routing to siblings. Three dense sentences that mostly earn their place; enumerating every returned field is somewhat redundant given an output schema exists, but it remains scannable.

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 a list tool with annotations covering the safety profile and an output schema covering return shape, the description still supplies the reaction-family semantics and sibling routing an agent needs to call it correctly. No meaningful gap remains.

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 baseline is 3. The description adds meaning on top of the schema: the unread/reaction interaction ("hidden reactions never count as unread") and the emoji payload in reaction messages, which the schema's terse flag descriptions do not fully convey.

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?

States a specific verb and resource ("List messages received by this address") plus ordering ("newest first"), which cleanly separates it from the sibling list_sent. An agent can pick this 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?

Explicitly routes to alternatives with conditions: "Use get_message for a full body and get_thread for the conversation around a message." It also states the condition that governs reaction visibility (include_reactions). Nothing about when to choose this tool is left to inference.

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

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

Annotations already declare the safe, idempotent, read-only profile, so the description's job is lighter. It adds real behavioral context the annotations don't: unsent drafts appear with time null, results are newest-first, and each row carries per-recipient delivery state. It stops short of describing volume or paging limits.

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?

Two sentences with no filler. The scope and ordering come first, and the sibling routing is a compact trailing pointer that earns its place.

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?

An output schema exists, so return values need no explanation, and the annotations carry the safety profile. The description covers the ordering and draft-inclusion nuances an agent would otherwise guess wrong on; only pagination behavior is left to the schema defaults.

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 100%, so limit, offset and include_reactions are already fully documented in the schema. The description adds no syntax or format guidance for them (e.g., what 'number of newest messages to skip' implies for paging), so the baseline 3 is appropriate.

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?

States a specific verb+resource (list messages sent by this address) and pins down the scope with the non-obvious inclusion of unsent drafts. It also explicitly names the sibling it is not, delivery_status, so an agent can separate the two without opening either 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 explicitly routes the agent to delivery_status when a single message's per-recipient detail is wanted, which is the main ambiguity for this family. It doesn't state exclusions against other list tools (list_messages, get_thread), but the sent-vs-all distinction is implied by the name and description.

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

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

Annotations already declare the state-changing, idempotent, non-destructive profile, so the bar is lower. The description adds useful scope detail ('including reaction messages listed with include_reactions'), clarifying what actually gets marked, but says nothing about permissions or failure behavior.

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?

Two tight sentences, purpose front-loaded, with the get_message caveat as a natural follow-up. No filler.

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?

Output schema and annotations are present, so return values and safety profile need not be restated. The description covers purpose, scope, and the key caveat; only permission/prerequisite details are absent, which is a minor gap.

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 100% and the single ids parameter is fully documented with type, pattern, and maxItems. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

States a specific verb+resource ('Mark received messages as read') and explicitly distinguishes its effect from the sibling get_message, which does not mark messages read. An agent can tell what this does and how it differs from reading.

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?

Provides clear usage context by noting that reading via get_message does not mark a message read, implying this tool is required when read state must change. It does not, however, state exclusions such as whether it applies to sent messages or drafts.

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

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

Goes beyond the annotations (idempotentHint, destructiveHint=false) by disclosing the replace-on-new-emoji semantics, the one-reaction-per-person limit, the side effect of notifying other participants, and the error cases. That is meaningful behavioral context a write operation needs.

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?

Three short sentences, fully front-loaded: the primary action, its semantics, the side effect, and the failure modes. No filler.

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 an output schema present, return values need not be explained, and the description covers the remaining gaps: replacement semantics, notification side effect, and error conditions. Nothing needed to invoke 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 coverage is 100%, so the baseline is 3; the description adds the effect of the emoji parameter (a new emoji replaces the previous, so setting is effectively an upsert) that the schema does not convey. It does not restate the null-clears-your-reaction convention, which the schema already covers.

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?

States a specific verb and resource ('Set or clear your emoji reaction on a message') with scope that clearly separates it from siblings like mark_read, send_message, or reply. An agent can select it 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?

Gives explicit failure conditions (drafts and terminal messages) and the one-reaction-per-person rule, which tells the agent when the call will not succeed. It does not name sibling alternatives, but the usage context is otherwise clear.

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

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

Beyond the write/non-idempotent/destructive annotations, it discloses that messages are immutable and cannot be edited or recalled, the default recipient set ('everyone on the parent … except you'), the failure modes for terminal and no-reply parents, secret redaction, and attachment handling (sha256 refusal, server-side compression). This is genuinely additive behavioral context.

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?

Purpose is front-loaded and every sentence carries operational information — behavior, recipients, failure modes, secrets, attachments. It is dense with semicolon-joined clauses and a separate File guidance sentence, which reads slightly packed 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?

With an output schema present, return values need no explanation, and the description covers the remaining agent-critical concerns: recipient defaults, refusal/failure conditions, immutability, redaction, and attachment constraints. An agent has everything needed to call this 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?

Schema description coverage is already 100%, so the baseline is 3. The description still adds meaning the schema does not: how recipients narrows or widens the reply-all default, when allow_no_reply applies, and when to supply sha256 or choose data_text over data_base64.

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 ('Send an immediate reply to a message') and immediately clarifies the defining behavior — it is 'linking it into that thread' — which separates it from the plain send_message sibling. The 'immediate' qualifier also implicitly distinguishes it from the draft-based path (create_draft/send_draft).

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 operating context ('send within the user's requested task or authorized automation') and explicit when-not conditions: fails when the parent is terminal, and is refused for no-reply parents unless allow_no_reply is set. It does not name an alternative tool (e.g. send_message for a fresh thread), so it stops short of a full when/when-not/alternative map.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds substantive behavior: literal addresses pass through unchanged, there are no short-name defaults, and unmatched names fail loudly rather than silently. No return format is described, but an output schema exists to cover that.

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?

A single dense sentence, front-loaded with the core action, followed by two short clauses covering pass-through, the no-defaults constraint, and the failure mode. No filler.

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 a one-parameter, read-only resolver with an output schema, the description covers action, scope, edge case, and failure behavior. Only the post-resolution workflow (which sending tool to feed the result into) is left implicit.

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 baseline is 3, but the description adds meaning the schema does not: it explains that only a literal @user@domain succeeds and that the 'short name' the schema advertises will in fact fail, which prevents a wasted call.

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?

States a specific verb+resource ('Resolve a recipient to a full fmsg address') and immediately disambiguates from the send-path siblings by stressing 'without sending anything'. An agent can tell this apart from send_message/reply without opening either 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?

Gives clear context (resolve a recipient before sending) and an explicit failure path ('ask the user for the full address'), which is real operational guidance. It never names a sibling tool as the follow-up action, but the when-to-use condition is unambiguous.

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

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

Goes well beyond the destructiveHint/non-idempotent annotations by stating the message becomes immutable once sent (cannot be edited or recalled) and describing refusal handling: the host's reason is returned verbatim and the message stays a draft. These are exactly the behavioral traits an agent needs before committing an irreversible action.

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 the action and its precondition, then the irreversible consequence, then authorization scope, then failure behavior. No filler, no repetition of the schema.

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?

An output schema exists, so return values need no explanation; the description still covers the prerequisite, the irreversibility, the authorization boundary and error semantics. Nothing an agent needs before calling this one-param write tool 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 100% and the single 'id' parameter is fully documented ('the draft to send', numeric pattern). The description adds no syntax or constraint detail beyond that, so the baseline 3 applies.

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?

States a specific verb (send) and resource (a draft made with create_draft), and clarifies that attachments go along and it happens immediately. It is clearly distinguishable from create_draft (which makes the draft) and send_message (which composes/sends new mail).

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 names the prerequisite tool (create_draft) and sets a scope condition: send only within the user's requested task or authorized automation. It does not explicitly contrast with send_message or reply, so the agent must infer the alternative routing, but the when-to-use context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description goes well beyond them: messages are immutable and cannot be edited or recalled, secrets are redacted, and host rejections are returned verbatim. The immutability and redaction notes are exactly the kind of consequence detail the hints cannot convey.

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?

Six sentences, each carrying distinct information — immutability, authorization scope, addressing, body format, redaction, rejection behavior, sibling routing, and attachment handling. The core action and its irreversibility are front-loaded with no filler.

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?

An output schema exists, so return values and delivery errors need no explanation here. Combined with full schema coverage and strong annotations, the description supplies everything an agent needs: irreversibility, the sha256 abort condition, addressing flexibility, and the routing rule to reply.

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 baseline is 3, but the description adds real operational meaning: recipients may be short names, body is Markdown by default, use data_text vs data_base64 by size, and supply sha256 when computable because mismatched bytes abort the whole send. It also notes fmsg compresses files, so callers need not pre-compress, which the schema does not say.

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?

States a specific verb and resource ('Send a new message immediately, starting a new thread') and explicitly distinguishes itself from the sibling tool that handles continuations ('To continue an existing conversation use reply instead'). An agent can differentiate send_message from reply, send_draft, and create_draft without opening any 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?

Gives an explicit authorization boundary ('Send within the user's requested task or authorized automation') and names the alternative with the condition that selects it ('To continue an existing conversation use reply instead'). This is the when/when-not/alternative pattern at full strength.

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

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

Annotations only declare readOnly/openWorld/non-idempotent/non-destructive; the description adds the genuinely non-obvious traits: blocking semantics, 230s hard cap, that a server restart returns 'interrupted' with nothing replayed or lost, that same-thread messages within settle_seconds collapse into one result, and which messages are silently skipped. This is exactly the extra context annotations cannot carry.

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?

Front-loaded purpose followed by labeled sections (When, Loop, Skipped, Limits) makes it scannable and nearly every sentence carries operational content. It is dense and uses unexplained output-field names ('reply_target_id', 'pending_ids'), which slightly hurts readability, though the output schema presumably defines them.

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 a blocking, stateful, loop-driven tool this covers the full agent decision surface: trigger, iteration protocol, aggregation, skip rules, error/interruption recovery, and time budget. With an output schema present, return-value detail is rightly delegated, so nothing material 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 coverage is 100%, so the baseline is 3, but the description adds real usage semantics beyond the field docs: after_id must be threaded through each loop iteration, settle_seconds drives the one-result aggregation rule, and timeout_seconds is bounded at 230. It does not explain 'from' or 'thread_of' beyond the schema, hence 4 rather than 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 first sentence gives a specific verb (block/return) and resource (next inbound message) plus the scope (with its thread context) and even the follow-on action ('so you can answer with reply'). It is clearly distinguishable from siblings like list_messages, get_message and get_thread, which are non-blocking reads.

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 'When:' line states the trigger (user asks to chat / keep replying / respond to the next message), the 'Loop:' line prescribes the wait → reply → wait cycle, and the 'Skipped:' section names the alternative for out-of-thread messages ('read them with get_thread before waiting again'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description restates what is returned (address, API URL, version) but that content is also covered by the existing output schema, so it adds little behavioral context about auth, failures, or limits.

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?

Two short sentences, identity scope front-loaded and the invocation hint placed last where it is easy to act on. The semicolon clause is slightly dense but nothing is wasted.

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 a no-arg, read-only diagnostic tool with an output schema, the description supplies purpose, return contents at a summary level, and a when-to-call trigger. Nothing an agent needs to invoke 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?

The tool takes zero parameters, so schema semantics are a non-issue and the baseline is 4. There is nothing for the description to disambiguate.

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 set: reports the fmsg address the server acts as, the Web API URL, short-name resolution, and server version. That is far more precise than the title 'Show fmsg identity'. It does not explicitly contrast itself with resolve_address, which is the nearest sibling, so it stops short of a 5.

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?

"Call this first if unsure who you are sending as" gives a concrete trigger condition, which is unusual and useful. It does not state when NOT to call it or name resolve_address as the alternative for name lookups, so it is clear context without full routing guidance.

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