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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds substantial context beyond these: it explains the destructive nature ('The message is destroyed rather than paused'), idempotency ('nothing happens twice'), and the fact that it never reaches a mail server. It also clarifies that cancellation is not reversible. No contradiction with annotations; description enriches the agent's understanding.

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 fairly long but every sentence contributes critical information about limits, idempotency, destructiveness, and scope. It is front-loaded with the core action and then systematically covers exceptions and safety. While concise would be shorter, the structure is logical and efficient; a 4 is justified for its clarity and organization.

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 tool with one parameter, an output schema (not shown but present), and rich annotations, the description covers all necessary behavioral aspects: what happens when already sent, when already cancelled, repetition safety, irreversibility, permission boundaries, and how to verify. It addresses edge cases and gives the agent complete information to act reliably. This is a model 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?

There is one parameter (outgoingEmailId) with 100% schema description coverage: 'The identifier of the queued message, exactly as the sending tool returned it in outgoingEmailId.' The description does not add additional parameter-level details beyond this, but the schema already fully explains it. Baseline 3 is appropriate since the schema does the heavy lifting and the description doesn't need to compensate.

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 clearly states the tool's purpose: 'Stops a message you queued from being sent, while it is still waiting.' It uses a specific verb (stops) and resource (message you queued), and distinguishes itself from siblings by explicitly noting it cannot recall already-transmitted messages and mentioning get_outgoing_email as an alternative. This fully clarifies what it does and differentiates it from related tools.

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 usage guidance: it says when to use (while waiting), when not to use (after transmission), and gives constraints such as 'You can only cancel a message you queued yourself.' It also advises checking the returned state or calling get_outgoing_email rather than assuming success. This is more than enough for an agent to choose appropriately.

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 annotations (which only indicate non-read-only, non-idempotent, non-destructive), the description discloses critical behaviors: writes go to local state only, no mail is sent or touched, duplicate calls result in an addressHeldByAnotherContact error because each address is globally unique, and user consent is required before writing. These details significantly expand the agent's 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 concise yet information-dense, with each sentence serving a clear purpose: purpose, scope, duplicate behavior, and consent. It front-loads the core purpose in the first sentence and then adds necessary caveats without fluff. No wasted words.

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?

Given the tool's complexity (global uniqueness, duplicate handling, consent requirement) and the fact that an output schema exists, the description is complete. It covers the write scope, the failure mode for duplicates, the alternative tool to use, and the need for user consent. No significant behavioral gaps remain that aren't already answered by the schema or annotations.

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 input schema already covers all four parameters with detailed descriptions (100% coverage), so the baseline is 3. The description does add high-level context (e.g., 'every address they use' and 'optional note') but does not introduce new parameter-level semantics beyond what the schema already states, such as the uniqueness constraint on addresses or the requirement that preferredAddress must be one of addresses. It reinforces but does not substantially augment the schema.

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 verb and resource: 'Records a person in MailFathom's own contact book' and enumerates the exact fields (name, addresses, preferred address, optional note). It clearly distinguishes from sibling tools like get_contact, update_contact, and delete_contact by explicitly stating that it creates a record and advising to look up existing contacts with get_contact instead of writing a second record.

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 gives explicit when-to-use and when-not-to-use guidance: it states that duplicate writes should be avoided and directs the agent to 'look that contact up with get_contact rather than writing a second record.' It also provides context that the tool writes to local state only, so it is appropriate for adding a person to the contact book without touching mail, and it even includes a consent requirement ('Ask the person you are acting for').

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?

The description adds significant behavioral detail beyond the annotations (which already mark destructive and idempotent). It explicitly states that deletion is not soft-marked, that missing contacts are reported as successful erasure (matching idempotentHint), and that no mail is deleted or server contacted—clarifying the exact side effects. This aligns with annotations and provides additional context the agent needs to understand consequences.

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 efficient and well-structured. It leads with the core purpose, then explains irreversibility, scope of deletion, idempotent behavior, and a safety note—all in about five sentences. Every sentence contributes new, non-redundant information, and nothing is overly verbose.

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?

Given the complexity of a destructive operation, the description is comprehensive. It covers side effects (no mail deletion, no server contact), irreversibility, unusual behavior for missing contacts, and even provides a human-facing confirmation instruction. The presence of an output schema means return value documentation is not needed. All necessary behavioral and safety details are included.

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 provides 100% coverage for the single parameter `contactId`, including a detailed description of its source and the caveat to read via get_contact first. The main description adds only that all addresses are removed, which is a behavior detail but not parameter-specific semantics. Since the schema covers the parameter well, the description doesn't need to add more; 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?

The description clearly states the tool erases one person from MailFathom's contact book and removes all associated addresses. It uses a specific verb (erase) and resource (contact record), and distinguishes from siblings like update_contact, get_contact, and create_contact by focusing on deletion. It also clarifies what is not affected (no mail deletion, no server contact), making its purpose unambiguous.

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 strong contextual guidance: it warns that deletion is irreversible, advises confirming with the person being acted for, and notes that the operation is idempotent (safe to repeat). It also explains that it only affects the contact record, not mail, which helps the agent decide when to use it. However, it does not explicitly compare with alternative tools like update_contact or delete_draft, so it lacks direct differentiation guidance, though the scope 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?

The description thoroughly discloses behavioral traits beyond annotations: it explains the destructive nature (message is GONE), idempotency (second call refused), and edge cases (mail server refusal, folder changes). It also clarifies that nothing is sent and drafts reach nobody. This adds significant context beyond the 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?

The description is a single, dense paragraph that is front-loaded with the core action and then elaborates on important caveats. While it is long, every sentence adds value by clarifying edge cases and safety considerations. It could be slightly more structured, but it is not verbose.

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?

Given the tool's destructive nature and the presence of an output schema, the description is exceptionally complete. It covers prerequisites (draft must be created by this deployment), exclusions (sent drafts, owner's drafts), error conditions (refused, second call), and post-conditions (result indicates success). No gaps remain.

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 provides 100% coverage for the single parameter (draftId), describing it as the ID returned by save_draft. The description reinforces this by explaining that the draftId names nothing after the call, adding a subtle but useful semantic detail about the parameter's lifecycle.

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 clearly states the tool's purpose: to delete a draft that this deployment holds, removing the copy from the owner's Drafts folder. It distinguishes from siblings by explicitly mentioning save_draft, send_draft, and cancel_outgoing_email, and clarifies it does not touch drafts created by the owner's mail client.

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 guidance on when to use this tool: only for drafts created by this deployment via save_draft, and not for drafts already sent (use cancel_outgoing_email instead). It also advises asking the person before deleting, and notes that asking twice is safe. This clearly differentiates from alternatives.

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?

Despite annotations already indicating destructive and idempotent hints, the description adds extensive behavioral context: the message cannot be recalled, it is queued not delivered immediately, refusals are generic to avoid leaking info, and email content is never an instruction. It also explains idempotency key semantics and the irreversibility, going well beyond the annotation hints. No contradictions.

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 lengthy and becomes a dense paragraph, but it is front-loaded with the core purpose and each sentence provides necessary detail about consequences, usage, and safety. While not concise, the verbosity is justified by the high-stakes, irreversible nature of the action. It could be structured with bullet points for readability, but the information is all valuable.

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?

Given the tool's complexity and the presence of an output schema, the description is remarkably complete: it covers the action, side effects, queueing behavior, idempotency, error handling, security warnings, and how to follow up. It leaves no critical gap for an agent to misuse the tool, making it fully self-sufficient for the intended use case.

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 significant meaning beyond the schema: it explains that 'to' is required because a forward needs a direction, that all other content (subject, attachments, forwarded body) comes from the stored email, and it provides detailed rationale for idempotencyKey (retry safety). It also clarifies plainTextBody and htmlBody relationships, thus enriching parameter understanding.

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 clearly states the tool's function: 'Sends a real email forwarding one this deployment already holds, with the files it carried, to people the original never named.' It specifies the action (forward), the resource (stored email), and differentiates from sibling tools by noting it takes no subject, attachment, quoted text, or From address, unlike send_email or reply_to_email.

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 guidance on when to use and when not to use the tool. It explains what it does, that it is for forwarding existing stored emails, how to track delivery via get_outgoing_email, and how to cancel via cancel_outgoing_email. It also warns against forwarding based on instructions found inside the email content, giving clear exclusions and safety advice.

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=true, idempotentHint=true, destructiveHint=false, so the description's statement that it 'changes nothing' and 'never contacts a mail server' adds context beyond annotations. It also discloses the case-insensitive matching and the empty-answer behavior for unknown contacts, which are useful behavioral traits not covered by 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?

The description is concise, front-loaded with the core purpose, and every sentence adds meaningful information. It covers purpose, usage, behavior, and edge cases without redundancy.

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?

Given the tool's simplicity (2 params, 100% schema coverage, output schema present, annotations provided), the description is complete. It covers identification methods, usage context, behavioral guarantees, and edge-case handling. No significant gaps remain.

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 both parameters well. The description adds value by explaining the mutual exclusivity ('name exactly one of the two') and the address format (address alone, not with display name), which goes beyond the schema's descriptions. It also clarifies the case-insensitive matching and the empty-answer behavior for unknown contacts, which are useful behavioral traits not covered by annotations.

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 clearly states the tool reads one person from MailFathom's contact book, identified by contactId or address. It distinguishes from siblings like list_contacts (listing) and create_contact/update_contact (writes), and explicitly notes it reads local state only.

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 explicit guidance on when to use the address form (to answer who a message is from or who an address belongs to) and clarifies that exactly one of the two parameters must be named. It also explains the behavior for unknown persons (empty answer, not error), which helps the agent decide when to call this tool.

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 readOnlyHint and idempotentHint annotations, the description discloses significant non-obvious behaviors: per-email independent success, body/budget truncation via truncatedBy, no attachment bytes in responses, short-lived bearer download URLs, redaction of sensitive content with stable [redacted:category] markers, and that 'Nothing stored is rewritten by it.'

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 front-loaded with the core purpose and every paragraph is information-dense, but it is a long single block of text and repeats some details already present in the input schema, such as the 10-email cap and URL expiration. It would benefit from light structuring, though no sentence is purely 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?

Given the output schema and annotations, the description fully equips an agent: it covers invocation constraints, local-only behavior, partial success, truncation, attachment-link security, redaction semantics, and the guarantee that nothing is rewritten. An agent can decide safely whether and how to call 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?

Although the schema already has 100% parameter descriptions, the tool description adds behavioral meaning: exactly one of storedEmailIds or threadId must be supplied, more than 10 storedEmailIds causes refusal rather than truncation, includeSanitizedHtml costs an extra sanitization pass on the shared character budget, and includeAttachmentDownloadLinks mints expiring credential-free URLs without changing response size.

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 states a specific verb+resource: it 'Reads up to 10 emails already synchronized into MailFathom's local mailbox copy' and enumerates the returned content (headers, plain-text body, optional HTML body, attachment metadata). This clearly distinguishes it from sibling tools like list_emails or search_emails, which are for finding or listing rather than reading full email content.

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 gives explicit when-to-use rules: use storedEmailIds for particular emails or threadId for a whole conversation, and states that a call naming both, or neither, is refused. It also clarifies that the tool never contacts a mail server, so it should not be used when live mailbox access or marking-as-read behavior is expected.

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 indicate read-only, idempotent, non-destructive. The description adds crucial context: it reads a durable record and does not contact the mail server, so freshness is limited. It also discloses privacy limitations (only own messages) and what the response does not contain (subject/body/attachments). No contradictions.

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 appropriately detailed but well-structured: starts with a clear statement of purpose, then usage, then limitations. Each sentence adds value without redundancy, making it efficient for an agent to parse.

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?

Given the tool's complexity (status reporting, failure conditions, privacy constraints), the description covers all essential aspects. The output schema exists, so return details are not needed. The description compensates for annotations by providing behavioral nuances (freshness, non-live check).

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 is 100% covered, so baseline is 3. Description adds value by emphasizing the exact identifier type and provenance (returned by sending tool), reducing confusion. However, it doesn't elaborate on format or examples beyond the schema.

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 clearly states the tool reports the status and delivery details of a queued message, distinguishing it from sending tools. It specifies the exact resources (queued messages) and contrasts with sibling tools like send_email and reply_to_email.

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 says when to use: when unsure if a send went through, and when not to: use instead of sending again to avoid duplicate messages. Also clarifies limitations: cannot list mailbox sends and only works for messages queued by the user.

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 cover read-only/idempotent/non-destructive, but the description adds substantial context: it reads only the local copy, never contacts a mail server, and reports folder freshness and synchronization status. It also clarifies what it does not return (no mail, no server address, no credentials).

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 three sentences, each dense with useful information. It front-loads the primary purpose, then adds usage context, behavioral details, and exclusions without redundant or vague language.

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?

Given the tool's simplicity (no params, output schema present, annotations cover safety), the description fully covers what, when, and what to expect from the output. It explains the significance of synchronization state and explicitly lists what the tool does not return, making it complete for an agent to decide invocation.

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 the description cannot add parameter meaning; baseline for 0 params is 4. The description does explain that each account has an identifier and display name, which may be useful for subsequent calls, but this is not strictly parameter semantics.

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 clearly states a specific action: 'Lists the mail accounts this MailFathom deployment serves.' It distinguishes from sibling tools (get_email_content, search_emails, list_emails) which focus on emails, not account metadata.

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 instructs when to use the tool: 'Call it to learn which mailboxes exist and what to call them before narrowing a listing, a search, or a question to one.' It also communicates an implicit exclusion by noting it 'never contacts a mail server,' so it is not for live data.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds valuable context beyond that: 'Reads local state only: it never contacts a mail server and changes nothing.' It also discloses pagination limits (max 200, default 50) and the opaque cursor behavior, which are not inferable from 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?

The description is a single paragraph that front-loads the purpose, then covers behavioral traits, pagination, and alternatives. Every sentence earns its place—no fluff or repetition. It is detailed but appropriately sized for a multi-parameter paginated list tool.

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?

Given the tool's complexity (4 params, pagination, search semantics, origin filter) and the presence of an output schema, the description covers all essential aspects: read-only local state, ordering, pagination bounds, search and origin filtering, and the alternative to use get_contact for single-address resolution. It is complete without needing to explain return values the schema already covers.

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 input schema already describes all four parameters in detail (100% coverage), so the baseline is 3. The description adds extra context by explaining how search and origin narrow the page, and mentions the default page size. It does not describe the cursor or pageSize in depth, but the schema does that well, so the description provides marginal added value.

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 verb ('Lists') and resource ('people from MailFathom's own contact book'), and adds ordering and return scope ('ordered by name, with the addresses each of them uses'). This clearly distinguishes it from siblings like get_contact, which resolves a single address, and list_emails, which lists emails rather than contacts.

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 explicitly states when to use this tool versus a sibling: 'To resolve one address to the person using it, call get_contact with that address rather than searching for it here.' It also explains how to narrow results with search and origin, and warns that pagination is required because there is no way to get the whole book in one call.

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?

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing that it never contacts a mail server, never marks mail as read, and never returns body text, raw MIME, or attachment content. It also states the junk-folder exclusion, the 100-summary cap, opaque-cursor pagination, and per-folder currency reporting. No contradiction with 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?

Five sentences each convey a distinct fact: what is listed, what filters exist, the safety/scope constraints, junk behavior, and pagination/currentness. The enumeration of filters is long but appropriate given the tool's 15 parameters; no sentence 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?

Given the tool's complexity (15 parameters, pagination, filter semantics, local-only behavior) and the presence of an output schema, the description covers all aspects an agent needs to decide whether and how to call the tool: scope, ordering, filters, safety, junk handling, max page size, cursor, and freshness. The output schema covers return values, so their omission here is acceptable.

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?

Input schema coverage is 100%, so the schema already documents all 15 parameters in detail. The description only summarizes the filter categories (e.g., 'remote seen state, remote flagged (starred) state') without adding syntax, format, or constraint details beyond the schema. It meets the baseline but adds no new parameter semantics.

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 'Lists summaries of emails already synchronized into MailFathom's local mailbox copy, newest received first by default' – a specific verb, resource, and ordering. It lists the available filter dimensions and explicitly scopes to summaries only ('never returns body text, raw MIME, or attachment content'), distinguishing it from sibling tools like get_email_content.

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 conveys clear context for when to use this tool: it is a local-only, read-only operation that returns summaries and never contacts the mail server or marks mail as read. It also notes that junk mail is excluded unless includeJunkMail is set and that cursor reuse with different filters is refused. However, it does not explicitly name alternatives such as search_emails or get_email_content for body retrieval, so 'when to use vs alternatives' 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?

The description adds substantial behavioral detail beyond the annotations: it states the outcome is one-way, rewrites nothing about the person, writes only to local state, touches no mail, and returns only an outcome, not the record. Annotations only indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description provides critical side-effect and return-value context that is not captured elsewhere.

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 dense but every sentence earns its place: it explains the purpose, the uniqueness of the path, the effect on update_contact, the scope of side effects, and the return behavior. It is front-loaded with the main action and avoids jargon or fluff, making it both concise and informative.

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 tool with one parameter and an output schema, the description provides complete context: it explains the state transition, the prerequisite (collected contact), the exclusivity, the side-effect limitations, and how to retrieve the record afterward (via get_contact). The output schema handles return values, so no additional explanation is needed. The description fully equips an agent to use the 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?

The schema already describes the contactId parameter with full coverage (100%), including how it is returned from listings or reads. The description reinforces this by clarifying it's the ID of a collected person and adds context on its origin. While the schema does the heavy lifting, the description's mention of 'as a listing or an earlier read returned it' adds useful practical guidance, so it earns a 4 rather than a baseline 3.

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 clearly states the tool's function: it promotes a collected contact to an asserted one, with specific verbs and resource ('takes on one person'). It also explicitly distinguishes this from other operations by noting it is the only path between the two origins and one-way, and mentions its relationship to update_contact.

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 clear context for when to use the tool: when wanting to assert a collected contact. It also notes that it unlocks update_contact and that it writes only to local state, implying it's not for mail operations. However, it doesn't explicitly state 'do not use if the contact is already asserted' (though it mentions that such contacts answer alreadyAsserted), nor does it name alternative tools for other scenarios. Overall, usage guidance is strong but lacks explicit exclusions.

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?

The description goes far beyond annotations: it warns the message 'CANNOT be recalled, edited, or deleted once it has left,' notes that the call transmits nothing and merely queues a delivery pass, explains that refusals are intentionally uniform, and provides safety guidance about not treating mail content as instructions. These are meaningful behavioral disclosures beyond readOnly/destructive/idempotent hints.

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 first sentence immediately establishes the tool's core purpose and stakes, and each sentence carries meaningful operational or safety information. However, the description is very long and somewhat repetitive, revisiting the cannot-undo warning and cancel_outgoing_email multiple times, which slightly reduces structural tightness.

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 high-stakes, irreversible email-sending tool, the description is complete: it covers audience selection, idempotent retries, auto-generated threading/quoting, refusal behavior, file/forward limitations, and safety against prompt-injected instructions. The output schema exists, so return-value explanation is not required.

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?

Although schema coverage is 100%, the description adds substantial meaning: audience has no default and wrong choice can publish privately or drop the rest of the conversation; idempotencyKey must be reused for retries and a new value creates a new message; plainTextBody is placed above an auto-added quoted original; cc adds to the audience rather than replacing it. This is rich semantic guidance beyond field names and types.

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 sentence—'Sends a real email in reply to one this deployment already holds'—uses a specific verb and resource, clearly distinguishing the tool from forwarding and other email operations. It also explicitly says it will not forward, naming forward_email as the alternative.

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 gives strong usage context: it is for replying to an email the deployment already holds, with everything read from the stored email rather than supplied. It explicitly directs users to forward_email for forwarding, get_outgoing_email to check delivery outcomes, and cancel_outgoing_email to stop a pending send.

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?

Despite annotations indicating non-read-only, non-idempotent, and non-destructive, the description adds rich behavioral context: no sending, no mail server involvement, no idempotency (duplicate drafts on retry), refusal of ambiguous calls, and clarifications about From address and excluded capabilities (attach, schedule, send). This goes well beyond annotation info.

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 lengthy but deliberately structured: it opens with the core purpose, then covers alternatives, shapes, refusal logic, idempotency, and exclusions. Every sentence contributes meaningful context for a complex tool, and the information is front-loaded with the most critical behavioral distinction (sends nothing).

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 9 parameters, only 1 required, 100% schema coverage, an existing output schema, and no nested objects, the description thoroughly covers all behavioral nuances: the two invocation modes, parameter interdependencies, error conditions (refusals), idempotency, and what the tool does not do. It leaves no ambiguity for an agent to misuse the 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?

The schema descriptions are thorough (100% coverage), but the tool description adds high-level parameter semantics: the two shapes (own message vs. answer) dictate which parameters are required/refused, how to/cc/bcc behave differently in replies, and that account/subject are derived from the answered email. This is not present in the schema and significantly aids agent understanding.

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 clearly states the tool writes a draft and sends nothing, distinguishing from send_draft, update_draft, and delete_draft explicitly. It identifies the resource (draft) and the action (write) with precise scope.

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 states when to use it ('when the person you are acting for should read a message before it goes out') and contrasts with send_draft, update_draft, and delete_draft. It also clarifies the two distinct invocation shapes and refusal rules, giving thorough guidance on usage.

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=true and destructiveHint=false, but the description adds extensive behavioral context: never contacts a mail server, never marks as read, never returns raw MIME or attachments, retrieval mode is variable, attachment content is unsearchable, junk filtered by default, and result windows are not continuable. These details go well beyond 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?

The description is long but every sentence adds value. It is front-loaded with the core purpose and then systematically covers retrieval, filters, exclusions, and edge cases. While it could be broken into clearer sub-sections, it remains dense and purposeful without redundancy.

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 tool with 14 parameters and an output schema, the description covers all crucial edge cases: retrieval mode differences, attachment limitations, junk mail handling, window size cap and non-continuation, handling of no results, and interplay with listing. It also clarifies that the tool reads only local copies, which is critical for agent expectations.

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% with detailed per-parameter descriptions. The overall description adds semantic meaning by explaining how filters collectively narrow results (e.g., 'Narrows by account, folder, sender address...') and notes that filter combination is 'unrelated to queryText'. This provides high-level understanding beyond the schema.

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 clearly states the tool's purpose: searching synchronized local emails for text and returning ranked matches with bounded extracts. It specifies the resource (MailFathom's local mailbox copy) and the action (searches), and differentiates from siblings like list_emails (listing) and get_email_content (full content retrieval) by explicitly noting it never returns whole 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?

The description provides strong guidance on when to use this tool: it explains the retrieval modes (lexical/hybrid), the limitation of searching only local copies, and explicitly contrasts with list_emails for listing via queryText description. It also clarifies that no results is normal, guiding the agent on expected behavior.

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?

Despite detailed annotations (readOnlyHint false, openWorldHint true, idempotentHint true, destructiveHint true), the description adds substantial behavioral context: irreversibility ('CANNOT be recalled, edited, or deleted'), exact transmit semantics ('queued and never that anything was delivered'), idempotency mechanism ('the draft is the identity... repeated call answers with the record'), refusal behavior ('everything this deployment refuses a send for is asked again now'), and that the draft is not deleted. No contradictions with 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?

The description is long but every sentence delivers critical safety and behavior details; it is front-loaded with the core purpose. While not as compact as the TDQS 4.3 example, the verbosity is justified by the irreversible, high-stakes action. It is well-structured, progressing from what it does to consequences, alternatives, and edge cases, with no redundancy.

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?

Given the complexity (one simple parameter but high-stakes side effects), the description covers all angles: what happens (queued), how to check delivery (get_outgoing_email), how to cancel, idempotency, refusal handling, draft preservation, and pre-send editing. With an output schema present and annotations providing basic hints, the description fully explains the tool's behavior and what the agent needs to know, making it exceptionally complete.

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 input schema already fully describes the only parameter (draftId) as 'The draftId save_draft returned for the draft you are sending. A UUID, and the whole of what this call takes...' (100% coverage), so the description adds no new semantic meaning about the parameter itself. It reinforces the identity concept but that is behavioral, not parameter-focused. Given the schema coverage, a baseline of 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?

The description clearly states the tool sends a real email from a draft ('Sends a real email: the message a draft holds') and explicitly distinguishes it from siblings ('This is the one draft tool that causes mail to leave; save_draft, update_draft, and delete_draft send nothing.'), making its unique purpose unmistakable.

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 when-to-use guidance by naming alternatives and their behaviors ('save_draft, update_draft, and delete_draft send nothing'), advises editing first ('edit it with update_draft first'), and directs follow-up actions ('Call get_outgoing_email...' and 'cancel_outgoing_email to stop it'), covering both prerequisites and post-send steps.

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 annotation booleans, it discloses that the message cannot be recalled or edited, that results will say queued rather than delivered, that delivery happens moments later, and that follow-up must happen through get_outging_email or cancel_outging_email. It also warns against addressing messages to contacts seen only inside email content, which is security-relevant 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?

The description is dense and front-loaded, with the risk warning first and key operational consequences clearly stated. It is somewhat lengthy and repeats finality/irreversibility in a couple of places, but in a mutually destructive side-effect-heavy tool this redundancy is justifiable and there is no filler 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?

For an 8-parameter tool with a destructive, irreversible effect and many sibling email tools, this description is complete: it explains follow-up paths, cancelation possibilities, rejection semantics, not-supported cases, and idempotency. Since an output schema exists, the description does not need to explain return-value shape, and it responsibly defers that to get_outgoing_email and the schema.

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%, but the description still adds useful parameter-level semantics: idempotencyKey is required and retry-safe, a new key creates a new message, recipients must be literal addresses rather than contact-book names, and the From address is not an argument but derived from the account's configuration. These clarifications add genuine value on top of an already strong schema.

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 verb-and-resource statement: 'Sends a real email from a mailbox this deployment holds to the people you address it to.' It also distinguishes itself from siblings by explicitly saying it will not reply to or forward an existing message, schedule a send, or send to a mailing list, so the tool's scope is unmistakable.

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 gives explicit when-to-use and when-not-to-use guidance: treat every call as final, ask the principal before sending, use get_outgoing_email to learn what happened, use cancel_outgoing_email to stop a queued message, and do not use this tool for attaching, forwarding, replying, scheduling, or mailing-list sends. This is far more than a generic email-send warning.

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 annotations, the description explains durability ('written down durably and issued to the mail server by the account's next synchronization run'), result shape ('changeRecordId and the lifecycle'), idempotent retry behavior, reversibility, and the replace semantics that removes unlisted keywords. This is rich behavioral context that annotations alone do not provide.

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 a single dense paragraph but every sentence contributes essential information: purpose, required-value rule, durability, idempotency, reversibility, keyword replace caveat, and exclusions. It is front-loaded with the core action and then layers necessary nuance without redundancy.

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?

Given the tool's six parameters, complex keyword semantics, idempotency concerns, and output schema, the description covers all critical behavioral aspects: what happens on retry, how replace differs from add/remove, what cannot be changed, and how results are reported. It leaves no major operational 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?

Although the schema already documents each parameter in detail, the description adds crucial cross-parameter semantics: the requirement that at least one value be set, the interplay between keywordChange and keywords, the full-set replacement behavior of 'replace', and the requestId rules for deduplication versus new changes. This goes well beyond the schema descriptions.

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 verb and resource: 'Marks one email read or unread, stars or unstars it, and adds, removes, or replaces its keywords.' This clearly distinguishes the tool from siblings like delete_draft or send_email, and the closing exclusion ('never sets the answered or draft flags, never deletes mail, and never sends anything') reinforces its scope.

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 gives clear operational guidance: at least one value is required, keywordChange must accompany keywords, and same requestId semantics for retries. It also states exclusions versus other mail actions, though it does not explicitly name alternative sibling tools for cases like deleting or sending.

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 annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description discloses specific destructive behaviors: 'an address the new record does not name is removed, and an omitted note clears the one held.' It also states the scope of side effects ('Writes to local state only, and touches no mail') and the contactWasCollected restriction, providing rich operational context that annotations do not cover.

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, each earning its place: the first states purpose, the second explains the whole-record replacement model and key consequences, the third covers scope, prerequisites, and special limitations. The information is dense but structured, with no filler or 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?

Given moderate complexity (5 params, output schema present), the description covers purpose, usage guidance, preconditions, destructive side effects, scope (local state only, no mail), and a specific exception (contactWasCollected). It does not need to list return values because an output schema exists. The description is sufficient for an agent to safely and correctly invoke the 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?

Although the schema already describes each parameter 100%, the description adds critical collective semantics: 'State the whole record you want them to have — the name, every address, which one is preferred, and the note — rather than only what changes' explains that the parameters jointly define the desired final state, not a delta. It also explains consequences (removal of unnamed addresses, note clearing) that tie parameters together, going beyond the isolated per-field schema descriptions.

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 'Amends one person in MailFathom's own contact book,' using a specific verb ('Amends') and resource ('one person' in the contact book), clearly distinguishing it from siblings like create_contact (new), delete_contact (removal), and get_contact (read). It further clarifies it is not a mail operation, avoiding confusion with mail-focused tools.

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 provides explicit when-to-use guidance: 'Read the contact with get_contact first so nothing is dropped by accident' establishes a prerequisite. It also gives an exclusion/alternative: for contacts collected from arriving mail (contactWasCollected), only an operator via mfctl can take on the record, implying the tool should not be used for such contacts. Additionally, 'Writes to local state only, and touches no mail' sets boundaries for its scope.

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 annotations, the description discloses that the tool replaces the entire message, drops omitted fields (recipients, body, htmlBody), increments the version count, and re-derives answers from the answered email. It also states that drafts not held by the deployment are refused. Despite annotations indicating idempotent and destructive hints, the description aligns and adds depth about side effects, without contradicting 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?

The description is front-loaded with the core purpose, but it is a dense wall of text with some redundancy (e.g., 'Read the draft... send it all again' rephrases earlier warnings). While every sentence carries important information, better formatting would improve scannability; it's appropriately detailed for a 10-parameter complex tool.

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?

Given the tool's complexity (10 parameters, conditional requirements, restrictions on draft ownership, and answer behavior), the description covers all essential aspects: what it does, how to use parameters correctly, what it refuses, and side effects. The presence of an output schema relieves the need to describe return values, making this description complete and self-contained.

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 has 100% coverage with detailed descriptions for each parameter, providing a baseline of 3. The tool description adds valuable high-level rules about parameter combinations (account+subject vs answeredEmailId+answering) and warns that omitting fields silently drops them, which goes beyond the individual schema descriptions and helps correct invocation.

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 clearly states the tool 'Replaces the whole message of a draft this deployment holds' and explicitly says 'SENDS NOTHING', distinguishing it from send_draft. It also names the resource (draft) and the action (replace), making the purpose unambiguous.

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 gives explicit guidance on when to use the tool: only for drafts created by this deployment (identified by draftId from save_draft), and not for drafts from other clients or already sent via send_draft. It also contrasts with save_draft's shape and mentions cancel_outgoing_email for stopping sent messages, providing clear boundaries versus alternatives.

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