AIsa Agent Mail

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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 with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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 destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; 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 states a clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

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 no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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 destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description adds substantial context beyond those flags: irreversibility, no response body, shared-account implications, potential to affect other callers' inboxes, and the need for ownership confirmation. This fully discloses behavioral risks and 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?

Four tight sentences, front-loaded with the core effect, followed by return behavior, risks, and the alternative. Every sentence contributes new, non-redundant information with clear formatting (bold warnings, readable structure). 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 destructive, irreversible, shared-account mutation with no output schema, the description covers everything an agent needs to invoke safely: what it does, what it returns, why it is dangerous, how to confirm ownership, and what to do instead. Nothing meaningful 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 input schema already documents both parameters (inbox_id and Authorization). The description adds minor value by tying inbox_id to the recommended get_agentmail_inbox ownership check, but it does not add meaningful parameter-level detail 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?

Clear, specific verb ('Permanently deletes') and resource ('an inbox and the mail in it'). It clearly distinguishes from sibling delete_* tools that remove smaller items like drafts, messages, threads, or list entries, rather than the inbox itself.

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 tells the agent when not to use the tool ('To stop using an inbox without destroying it, simply leave it alone') and provides a prerequisite: confirm ownership from get_agentmail_inbox before calling. It also warns about the shared-account context, making the usage conditions 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 flag destructiveHint=true, but the description goes much further: it explains returns no body, irreversibility, shared-account side effects affecting other callers' drafts, and recommends a safe read-before-delete pattern. This is excellent behavioral disclosure beyond the structured 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?

Three sentences, each earning its place: what it does, return behavior, and critical caveats. The most important fact is front-loaded, and the safety advice is compactly appended 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 destructive delete tool with no output schema, the description covers the essential operational concerns: deletion target, no response body, irreversibility, account-sharing risk, and a suggested read-before-delete safeguard. Nothing an agent needs to invoke it appropriately 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%, so all three parameters (inbox_id, draft_id, Authorization) are already documented. The description adds no parameter-specific syntax or relationships, which meets the baseline but doesn't improve on 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?

Description states a specific action ('Permanently deletes an unsent draft') with resource scope, clearly distinguishing this from message/thread deletes by emphasizing it only targets unsent drafts. The first sentence is unambiguous and the tool's destructive nature is explicit.

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?

Description gives clear usage context: it is for unsent drafts, cannot be undone, and should be preceded by reading with get_agentmail_inbox_draft if unsure. It does not explicitly enumerate sibling alternatives, but the 'read it first' guidance effectively tells the agent when to use the read tool rather than acting directly.

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 by revealing non-obvious behavior: returns no body, permanently changes inbox acceptance/sending, read_only entries are platform-managed and cannot be removed, and writes are shared across all callers in the AgentMail workspace. This gives an agent the full behavioral picture even without 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?

Four compact sentences with no wasted words. The core action is front-loaded, and each following sentence contributes a distinct, necessary fact: no body, future side effect, read-only constraint, and shared workspace context.

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 description is complete for a destructive, output-less tool: precondition check, no response body, side effects, and shared workspace implications are all stated. Every important runtime behavior an agent needs to choose and invoke this safely is covered.

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 structured schema already documents all five parameters with descriptions and enums. The description adds only the 'allow or block list' framing, which maps directly to the type parameter but doesn't add significant new meaning 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 opens with a precise action: 'Removes one entry from an inbox's allow or block list.' This cleanly identifies the verb, resource, and scope, distinguishing it from the many sibling delete tools and general list-entry tools almost immediately.

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 actionable guidance for safe use: check with `get_agentmail_inbox_list_entry` first and understand the shared-workspace side effects. It doesn't explicitly contrast against `delete_agentmail_list_entry`, but the context is clear enough that no reasonable alternative is ambiguous.

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, but the description adds value beyond that: 'Returns no body' clarifies the response behavior, 'This cannot be undone' emphasizes irreversibility, and the shared-account warning explains a non-obvious consequence. These details are not present in the annotations or schema, so the description carries meaningful extra disclosure.

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 compact, front-loading the core action and key warning, then adding the alternative. Every sentence adds value: the action, the irreversibility, the shared-account implication, and the alternative tool. No fluff or 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 destructive operation with no output schema and annotations covering safety, the description covers all essential aspects: what it does, that it returns nothing, that it cannot be undone, that the message might belong to another caller, and how to achieve a non-destructive alternative. An agent has everything needed to decide whether to call it.

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 all three parameters (inbox_id, message_id, Authorization) are already documented. The description does not add any parameter-specific nuance beyond what the schema provides; the shared-account warning is contextual but not parameter-level. Baseline 3 is appropriate when the schema handles parameter documentation.

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 'Permanently deletes one message' – a precise verb and resource. It distinguishes itself from sibling tools like delete_agentmail_inbox_thread and delete_agentmail_inbox_draft by explicitly stating it targets a single message, and it reinforces the permanence, which is a clear differentiator.

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 when-not-to-use guidance: 'To hide a message from a workflow without destroying it, relabel it with `patch_agentmail_inbox_message` instead.' It also warns about the shared-account context, telling the agent that the message may not belong to the caller, which is critical for deciding whether deletion is appropriate.

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 useful behavior beyond the annotations: no response body, multi-message destruction, irreversibility, and shared-account scope. However, it claims the delete is always permanent, conflicting with the schema's `permanent` parameter whose description says false moves to trash, so the behavioral disclosure is materially inconsistent.

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 front-loads the outcome and every clause earns its place, including no-body response, cross-caller reach, and the safer alternative. It is dense but not bloated, so it remains appropriately concise.

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?

It covers cross-caller consequences, the read-first prerequisite, the no-response-body fact, and the hide alternative. Missing is reconciliation with the optional `permanent` parameter, so an agent cannot tell from this description when the action truly destroys versus moves to trash.

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 parameters are already documented and the description adds no parameter-level detail. The blanket use of 'permanently' obscures the `permanent` flag semantics rather than enhancing them, keeping 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?

The description clearly identifies the action and resource: permanently deleting a thread and every message in it, and it points to a non-destructive alternative. It loses the fifth point because it states permanence is stated unconditionally, while the schema's optional `permanent` parameter implies the default may move to trash instead.

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 tells the agent to read the thread with `get_agentmail_inbox_thread` first and warns that deletion affects other callers' inboxes because they share one AccountMail account. It also gives a clear when-not path: to hide instead, relabel with `patch_agentmail_inbox_thread`.

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 destructiveHint annotation, the description discloses that removal affects every inbox in the account, including other callers', that the call returns no body, and that read-only entries cannot be removed. These behavioral warnings and side effects are valuable context the annotations do not 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?

Three sentences, each earning its place: purpose and key scoping warning first, then the alternative tool, then a safeguard precondition. The strongest warning is front-loaded and there is no redundant 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 destructive account-wide mutation operation, the description covers the core action, scope, side effects, prerequisites, and the relevant sibling. Without an output schema, it also discloses that no body is returned, so no critical calling context 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 schema already documents all four parameters with full coverage, so the baseline is 3, but the description adds meaning by tying `read_only` entries to a removal constraint and clarifying the account-wide nature of the list. This goes slightly beyond the schema field 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 states a specific verb and resource: 'Removes one entry from an account-wide allow or block list.' It also explicitly differentiates this tool from the inbox-scoped sibling, making its scope 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 clearly names the alternative `delete_agentmail_inbox_list_entry` as the narrower action, giving an explicit when-not-to-use condition. It additionally instructs the agent to check `read_only` with `get_agentmail_list_entry` before attempting removal, providing a concrete prerequisite.

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 valuable context beyond the annotations: deletes multiple messages, returns no body, reaches other callers' inboxes, and can destroy another caller's conversation. However, the blanket 'Permanently deletes' and 'cannot be undone' conflicts with the schema's `permanent` parameter, which allows moving to trash when false; that non-permanent path is not disclosed.

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 the core action and outcome, with safety warnings and alternative routing later. The description is a little long but every part earns its place; minor redundancy exists between 'Permanently deletes' and 'cannot be undone.'

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?

Covers the dangerous cross-account behavior, return body, and scoped alternative very well. The missing piece is the `permanent: false` path and when a caller would want trash instead of permanent deletion, which is critical for safely invoking this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but the description misrepresents the `permanent` parameter by implying deletion is always permanent and irreversible. It does provide useful context that `thread_id` is the only identifier, but the misleading permanent/trash distinction drops it below 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 action ('permanently deletes a thread addressed by id alone') and resource ('every message in it'), and distinguishes it from the scoped sibling `delete_agentmail_inbox_thread` by explicitly naming that twin. An agent can tell what this tool does and how it differs.

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: read first with `get_agentmail_thread`, warns that it affects inboxes created by other callers, and names the safer scoped alternative `delete_agentmail_inbox_thread`. This is clear when-to-use and when-not-to-use insight.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds genuinely useful behavioral context beyond annotations: the shared-account implication that this crosses inbox boundaries created by other callers. 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?

The key scoping constraint is front-loaded in the first clause and the routing guidance is efficient. The long list of returned fields is somewhat redundant given the output schema exists, making the description slightly verbose, but every sentence otherwise 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?

Complete for an org-wide fetch tool whose annotations already disclose the read-only/idempotent profile. It explains the shared-account nuance, the difference from the inbox-scoped twin, and what fields come back; with an output schema present, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (draft_id and Authorization), so the schema does the heavy lifting. The description lists the returned draft fields (draft_id, inbox_id, to, cc, etc.) which is output-shape info rather than parameter semantics, and with an output schema present it adds little. 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 opens with a specific verb-resource pair ('Fetches one unsent draft by id') and immediately states the distinguishing scope: it works without naming an inbox and spans every inbox in the account. It explicitly names the inbox-scoped twin get_agentmail_inbox_draft, so an agent can separate this from the many get_agentmail_* siblings without opening schemas.

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 routing guidance: the organization-wide view is for reaching inboxes other callers created in the shared AgentMail account, and it names the alternative get_agentmail_inbox_draft as the one to use 'when a single inbox is meant.' The selection criterion is concrete and actionable.

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 that the tool returns metadata only, that bytes are not inlined, that the download_url is short-lived with expires_at, and that shared account use reaches inboxes created by other callers. These are meaningful behavioral details an agent needs to handle the result 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 description is front-loaded with the core action and scope, then adds return-field details in a compact list, and closes with routing guidance. Each sentence contributes necessary information; there is 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?

Given the simple three-parameter schema, the readOnly/idempotent annotations, and the presence of an output schema, the description is complete: it covers scope, output fields, download URL lifetime, and sibling routing. Nothing needed to call or interpret the tool is left out.

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 present with 100% coverage, so the baseline is 3. The description adds value by clarifying that draft_id is sufficient 'by id alone' in the organization-wide namespace, distinguishing it from inbox-scoped identifiers. It does not deeply explain Authorization or ID formats, but the schema already covers the basic meaning.

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: 'Fetches metadata for one attachment on a draft addressed by id alone.' It clearly differentiates itself from the inbox-scoped twin by noting this is the 'organization-wide view spanning every inbox in the account.' An agent can immediately understand what this tool does and how it differs from sibling 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?

Usage guidance is explicit: it describes the organization-wide scope and then names the alternative, saying 'the inbox-scoped twin get_agentmail_inbox_draft_attachment is the one to use when a single inbox is meant.' This tells the agent exactly when to choose this tool versus its sibling.

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 mark this as read-only, idempotent, and non-destructive, but the description adds meaningful behavioral detail: the exact response shape, pagination via next_page_token, and the fact that list items carry only preview while full text/html requires get_agentmail_draft. 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?

The description is somewhat long and repeats the 'every inbox in the account' idea twice, but it is well-structured, front-loads the core purpose, and each sentence adds distinct information such as response fields, preview-only behavior, and sibling routing.

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 rich output schema, annotations, and sibling context, the description covers everything needed to select and call the tool correctly. It explains scope, pagination, list-vs-detail behavior, and the discriminant between this and the inbox-scoped sibling.

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 documents all seven parameters. The description adds value by explaining pagination and response fields, but it provides no additional detail about the parameters themselves. This matches the baseline for fully covered schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise action and resource: listing unsent drafts across every inbox in the account. It clearly distinguishes itself from the inbox-scoped sibling get_agentmail_inbox_drafts, so an agent can identify this tool without opening schemas.

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 explains that this is the organization-wide view spanning every inbox, and that the inbox-scoped twin get_agentmail_inbox_drafts should be used when a single inbox is intended. It also notes that all AIsa callers share one account, giving a concrete reason to prefer the scoped alternative.

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 and idempotentHint, but the description adds behavioral nuance: it returns settings only, no mail, and lists the exact fields. This goes beyond the structured annotations, clarifying the scope of the read operation.

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 with no filler. The main action is front-loaded, followed by the return fields, a clarifying exclusion, and pointers to related tools. Every sentence 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?

The description covers what the tool returns (settings fields), what it does not return (mail), how to find IDs, and where to go for messages and threads. With an output schema present and strong annotations, nothing essential is missing for correct 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?

Both parameters are fully documented in the schema (inbox_id and Authorization) with descriptions, so schema coverage is 100%. The description adds no additional parameter-level detail beyond referencing inbox_id in the action, which is redundant. 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 states a specific verb ('Fetches') and resource ('one inbox by inbox_id'), lists the returned fields, and explicitly distinguishes from sibling tools that handle messages and threads by naming them. It leaves no ambiguity about what this tool does.

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 routing: 'For the messages in it use get_agentmail_inbox_messages, for conversations get_agentmail_inbox_threads. Discover ids with get_agentmail_inboxes.' This tells the agent exactly when to use this tool versus alternatives and how to find the required inbox_id.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the 'unsent draft' qualifier and 'in full' detail, which clarifies the scope beyond raw annotations but does not add behavioral context like error handling or pagination. With annotations handling the primary behavioral traits, a 3 is appropriate.

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 two sentences with no redundant content. The first sentence leads with the action and specifies the return fields, while the second succinctly points to related operations. It is front-loaded and every sentence earns its place, achieving excellent conciseness.

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 tool has an output schema, so return values are defined separately, and annotations cover safety, reducing the burden on the description. The description explains the tool's purpose and suggests next steps, covering the essential context for an agent. It lacks explicit error handling or edge cases, but for a simple fetch operation, it is sufficiently 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?

Schema description coverage is 100%, and each parameter (draft_id, inbox_id, Authorization) already has a clear description. The tool description does not add any additional parameter semantics; it merely lists the fields returned, which are separate from the input parameters. Since the schema fully documents the parameters, the description adds no value here, placing it at the 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 verb 'fetches' and the resource 'one unsent draft in full', and enumerates the returned fields. It distinguishes from plural-fetch siblings by saying 'one' draft, though it doesn't explicitly differentiate from get_agentmail_draft, which may target drafts without inbox context. Overall, purpose is specific and 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 implies usage for retrieving a single draft and suggests follow-up actions (edit/send), but it does not explicitly state when to use this tool over alternatives like get_agentmail_draft or get_agentmail_inbox_drafts, nor does it provide exclusions. The context is clear but not explicit, so it meets the 'implied usage' criterion without stronger 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 already establish read-only, idempotent, non-destructive behavior, so the description earns credit for adding real behavioral context: the `download_url` is short-lived, has an `expires_at`, and the attachment bytes are not inlined. This is exactly the kind of operational detail an agent needs 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?

Four sentences, each earning its place: purpose, returned fields, critical expiration caveat, and source/alternative guidance. The most important constraint is front-loaded and there is 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?

Given that an output schema exists and the annotations cover safety, the description supplies everything missing for correct invocation: return field list, URL lifetime behavior, ID provenance, and sibling differentiation. Nothing critical 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 the baseline is 3, but the description meaningfully supplements the schema by explaining that `attachment_id` values come from the draft's `attachments` array and that the draft is an unsent one. This adds provenance that the bare parameter descriptions lack.

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: 'Fetches metadata for one attachment on an unsent draft.' It clearly distinguishes this tool from the sent-message sibling by naming the twin, so an agent can identify the correct scope 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?

The description explicitly narrows use to unsent drafts and tells the agent where the required IDs come from: the draft's `attachments` array on `get_agentmail_inbox_draft`. It also names the alternative for sent messages, `get_agentmail_inbox_message_attachment`, providing clear 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, and the description adds substantial value beyond those. It discloses pagination mechanics via `next_page_token`, the exact fields returned on each draft, the distinction between preview-only list items and full content, and the fact that drafts are not sent until the send endpoint is called. This gives an agent accurate expectations for downstream 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?

The description is compact yet information-dense, with the core function front-loaded in the first sentence. Every subsequent sentence earns its place by explaining output shape, list-item limitations, related follow-up tools, and the account-wide alternative.

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 description covers what an agent needs: scope, returned fields, pagination, the preview/full-content distinction, the send relationship, and the sibling tool for account-wide drafts. The output schema exists, so return-value details are reinforced structurally, and no critical behavioral 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?

Input schema coverage is 100%, so the baseline of 3 applies; the schema already documents each parameter. The description mentions pagination via `next_page_token`, which indirectly relates to `page_token`, but does not add new semantic meaning for `after`, `before`, `labels`, or `limit`. It does not need to compensate, so 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 opens with the specific verb 'Lists' and the precise resource 'unsent drafts in one inbox,' making the tool's function immediately clear. It also distinguishes itself from the account-wide `get_agentmail_drafts` and the single-draft `get_agentmail_inbox_draft`, which is critical given the large sibling list.

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 clearly states this is scoped to one inbox and explicitly points to `get_agentmail_drafts` as the account-wide alternative, giving an agent useful routing context. It also mentions that full `text` and `html` content comes from `get_agentmail_inbox_draft`, which guides follow-up calls. The guidance is implicit rather than an explicit 'use when / use instead' rule, so it falls just short of a 5.

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 mark it read-only/idempotent, but the description adds valuable context: the shared-account caveat (list includes other callers' inboxes), the return structure with pagination, and the field details. This goes beyond annotations and helps the agent understand side effects and scope.

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 slightly long but every sentence contributes: purpose, return fields, pagination, shared-account warning, and sibling references. Front-loaded with the main purpose. Could tighten wording but remains efficient.

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 operation with an output schema, the description covers return fields, pagination, scope caveat, and alternatives. It is complete for an agent to call correctly, with no missing critical information.

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 descriptions for all four parameters (limit, ascending, page_token, Authorization). The description mentions pagination with next_page_token but does not add semantics beyond the schema, so 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?

Clearly states 'Lists every inbox in the AgentMail account' with specific verb and resource, and distinguishes from get_agentmail_inbox (single) and post_agentmail_inbox (create).

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 names alternatives: 'Use get_agentmail_inbox for one inbox you already know the id of, and post_agentmail_inbox to create one.' Also warns that the list is not scoped to the caller, which is crucial for selecting 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the burden on the description. The description adds useful behavioral context: it returns a paginated list with count/limit/next_page_token, details the event fields, and clarifies that it reveals post-send activity. This goes beyond annotations without contradicting them.

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 sentences, each earning its place: purpose and scope, return envelope, event fields, and usage guidance with alternative routing. The purpose is front-loaded and no filler or redundant restatement of the tool name exists.

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 exists, the description need not explain return values in detail, but it still does usefully enumerate the event fields and pagination envelope. It also covers the relationship to a sibling. Minor gaps like default ordering or the meaning of openWorldHint are not essential for correct 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?

Schema description coverage is 100%, so the input schema already documents all parameters. The description only lightly touches pagination with 'page with next_page_token' and does not add extra meaning for limit, ascending, or Authorization. Baseline 3 is appropriate since the schema carries the semantic load.

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?

Description states a specific verb and resource: 'Lists delivery and activity events for one inbox.' It immediately frames the tool as the audit trail behind sends and receipts, and explicitly names the sibling get_agentmail_inbox_metrics as the alternative for aggregate counts, so the agent can distinguish 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?

Provides explicit when-to-use guidance: 'Use this to find out what happened to a message after post_agentmail_inbox_message_send returned, which the send call itself cannot tell you.' It also names the alternative for aggregate counts, giving a clear decision boundary between this tool and get_agentmail_inbox_metrics.

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, and destructiveHint=false, so the safety profile is well-covered. The description adds value by detailing the return shape (count, limit, next_page_token, entries) and per-entry fields, which goes beyond what annotations state. It does not contradict any annotation.

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 two sentences with zero fluff. It front-loads the purpose, then efficiently covers parameters, return shape, and the alternative tool. Every sentence earns its place, and it is easy to scan quickly.

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 presence of an output schema and comprehensive annotations, the description covers the essential aspects: purpose, parameters, return shape, pagination, and the sibling distinction. The only minor gap is that the direction values are not fully enumerated (e.g., 'reply' is omitted from the description), but the schema fills that in. Overall, it is quite complete for a read-only list operation.

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 does add interpretation for `direction` (inbound/outbound) and `type` (list kind), and it explains pagination via `next_page_token`. However, the direction explanation is slightly inaccurate because the schema enum includes 'reply', which is not purely inbound/outbound. This is a minor mismatch, so the added value is modest.

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 a precise resource ('one inbox's allow or block entries'), which clearly distinguishes it from the account-wide twin. It also explains that direction and type select the list kind, so an agent knows exactly what this tool does without needing to inspect the schema. This is a model of purpose clarity.

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 names the alternative tool, `get_agentmail_list_entries`, and frames it as the account-wide twin. This tells the agent when to prefer this tool (per-inbox) vs. the sibling (account-wide), which is a direct usage guideline. No other siblings are referenced, but the key distinction is 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds the meaningful caveat that read_only entries are platform-managed and cannot be deleted. It also clarifies what fields the fetch returns, providing useful 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 compact: one sentence states the operation, one sentence explains read_only semantics, and one sentence routes to the plural sibling. The field list is a bit long but front-loaded and purposeful.

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 simple single-entry fetch with an output schema and readOnly/idempotent annotations, the description is complete. It covers the operation, a key behavioral caveat, and directs the agent to the corresponding list operation.

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% for the five required parameters, so the baseline applies: the description adds little beyond schema field names. It maps 'allow or block' to the type parameter and mentions 'read_only', but this is output context rather than 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 states a specific verb and resource: 'Fetches one allow or block entry on an inbox.' It identifies the exact singular scoping (one entry) and lists the returned fields, making it clearly distinct from siblings like get_agentmail_inbox_list_entries and get_agentmail_list_entry.

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 paragraph explicitly points to the plural sibling for listing all entries, giving the agent a direct alternative. It does not enumerate all when-not-to-use scenarios, but the singular fetch behavior is clear enough.

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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by stating the message is returned 'in full' and by clarifying that this tool returns attachment metadata rather than raw MIME or attachment download URLs. It does not cover auth semantics, but the schema's Authorization parameter and annotations sufficiently cover side-effect concerns.

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 main action is front-loaded in a single sentence, and the sibling routing is appended compactly. The enumeration of result fields is slightly redundant given the output schema, which keeps this from a 5, but the definition is still focused and without 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 read-only single-message fetch with three fully documented parameters, an output schema, and annotations covering side effects, the description supplies the remaining selection context: full message scope, raw alternative, and attachment alternative. Nothing an agent needs to choose and 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?

Input schema has 100% description coverage for all three parameters, so the description does not need to add parameter detail. It adds no new input semantics, matching the baseline of 3 for high schema coverage.

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 ('Fetches one message in full') and enumerates the exact fields returned. It also differentiates itself from two closely related siblings by pointing to get_agentmail_inbox_message_raw for MIME source and get_agentmail_inbox_message_attachment for attachment URLs.

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 routing: if the caller needs the original MIME source, use the raw sibling; if they need an attachment download URL, use the attachment sibling. This tells the agent when this tool is appropriate and when it is not, which is exactly the needed guidance for this cluster of message tools.

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, and non-destructive. The description adds important behavioral context beyond annotations: bytes are not inlined, the download_url is short-lived with expires_at, and the output is metadata-only. This gives the agent actionable operational knowledge 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?

Four sentences, each earning its place: primary action and returned metadata, the non-inlining caveat and expiry, the attachment_id source, and sibling tool names. No fluff or 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?

Complete for a metadata-fetching tool: purpose, return values, time-sensitive URL, ID provenance, and sibling alternatives are all covered. Output schema further handles structural return details, and annotations cover safety.

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 baseline is 3. The description adds meaningful context for attachment_id by telling the agent it comes from the attachments array of get_agentmail_inbox_message, which helps construct a valid call. Other parameters are well covered by the schema itself.

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 starts with a specific verb and resource: 'Fetches metadata for one attachment on a message' and explicitly names the thread- and draft-level twin tools, distinguishing it from related attachment tools without needing to open schemas.

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 context: this tool is for message-level attachment metadata, provides the source of attachment IDs ('attachments array on get_agentmail_inbox_message'), and names the sibling twins for thread and draft attachments. It also instructs to fetch the download_url before expiration, guiding correct invocation.

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 signal read-only/idempotent/safe, and the description adds beyond them: bytes are not inlined, URL is short-lived and must be fetched before expires_at. This prevents a likely misuse where an agent assumes the raw bytes are returned directly.

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 result shape, then the operational caveat and routing guidance. 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 simple read-only retrieval with an output schema and full param schema, the description covers result format, expiry behavior, and the sibling alternative. Nothing essential 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 covers all three parameters (inbox_id, message_id, Authorization) at 100%, so the baseline applies. The description does not add parameter-specific semantics beyond what the schema already documents.

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 ('Returns') and exact resource: the original RFC 822 source of one message. Clearly distinguishes from sibling get_agentmail_inbox_message by mentioning parsed text/HTML, and enumerates return fields.

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 names use cases (headers, DKIM, exact MIME structure) and names the alternative for parsed text/HTML. Also warns to fetch download_url before expiry, guiding operational use.

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, and destructiveHint=false, so the safety profile is known. The description adds behavioral context: it specifies the return fields (count, limit, next_page_token, messages), explains pagination via next_page_token, and directs to get_agentmail_inbox_message for full bodies. This exceeds the minimal annotation coverage without contradicting 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 exceptionally concise: two sentences that front-load the core purpose and return structure, then pivot to sibling routing. Every sentence earns its place, with no redundancy or 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 tool's complexity (12 parameters) and the presence of an output schema, the description is complete: it explains the return format, pagination, how to access full message bodies, and how it differs from related tools. The agent has everything needed to call it correctly without opening 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 description coverage is 100%, so all 12 parameters are already documented with descriptions. The description adds context about pagination (next_page_token) and ordering ('newest first'), which clarifies the meaning of page_token and ascending parameters. However, it doesn't provide additional parameter-specific semantics beyond what the schema already offers, so the 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 lists messages in one inbox with a specific ordering ('newest first'). It distinguishes itself from siblings by explicitly naming get_agentmail_inbox_messages_search for searching and get_agentmail_inbox_threads for conversation grouping. The verb-resource pairing is specific and 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 explicit when-to-use guidance by naming the alternatives and the conditions that select them: 'To search rather than page, use get_agentmail_inbox_messages_search; to group by conversation, get_agentmail_inbox_threads.' It also implies this tool is for paging through messages, giving clear usage 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context about the return payload (count, limit, next_page_token, messages) and pagination via next_page_token, which goes beyond what annotations provide. 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 three sentences with no redundancy. It front-loads the core purpose, then mentions return fields and pagination, and finishes with sibling differentiation. Every sentence adds value, making it concise and well-structured.

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 moderate complexity (7 params, 3 required, output schema present) and that the schema already documents all parameters, the description fully covers the search semantics, pagination, and how to select this tool among siblings. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters (q, after, before, limit, inbox_id, page_token, Authorization) are fully documented in the schema itself. The tool description does not add extra parameter-level meaning beyond what the schema already provides, so a baseline score 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 performs full-text search across one inbox's messages, with a specific verb and resource. It explicitly distinguishes itself from sibling tools like get_agentmail_inbox_messages (for date-ordered listing) and get_agentmail_inbox_threads_search (for thread-level search), making it unambiguous which tool to choose.

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 versus alternatives: it's for query-based search, while get_agentmail_inbox_messages is for everything in date order, and get_agentmail_inbox_threads_search is for searching conversations. This clear routing eliminates ambiguity.

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 idempotentHint=true, so the description's job is to add context. It does: empty arrays mean no activity (not an error) and the response shape is not pinned, so agents must read returned keys. These are meaningful behavioral notes that go beyond the annotations, without contradiction.

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 moderately long but dense with information: purpose, key list, empty-array semantics, unpinned shape, and alternatives. It's front-loaded with the core purpose and each sentence earns its place. Slightly verbose in the key enumeration, but necessary for clarity.

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 an output schema exists, the description doesn't need to detail return values. It covers the tool's purpose, usage guidance, and two key behavioral nuances (empty arrays, unpinned shape). It's complete for an agent to select and invoke correctly, though it omits any note about authentication requirements, which the schema already conveys.

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 baseline is 3. The description doesn't add parameter-specific guidance (e.g., how to use start/end/period), but that's acceptable because the schema fully documents each parameter. The description focuses on output behavior, which is outside 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 it returns aggregate counters for one inbox, contrasting with get_agentmail_metrics (account-wide) and get_agentmail_inbox_events (individual events). The specific counter keys are enumerated, making the resource and scope 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?

Explicitly names the alternative tools and the conditions for using them: 'For individual events rather than counts use get_agentmail_inbox_events; for the account-wide totals, get_agentmail_metrics.' This leaves no ambiguity about when to select 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful detail about returning the full message list and metadata fields, but does not disclose additional behavioral traits such as ordering, pagination, or thread-scoping nuances beyond what the name and schema imply.

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 compact, front-loaded with the main action in the first clause, and the sibling pointer sentence is useful. The long list of returned fields is somewhat redundant with the output schema, but it helps an agent quickly understand what a 'full thread' includes.

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 simple read-only getter, the description is complete: all required parameters are documented in the schema, the output schema exists, annotations cover safety, and the description gives the core behavior plus an explicit alternative. Nothing critical is missing for an agent to invoke it 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 all three parameters are already documented. The description mentions thread_id and inbox_id only as returned fields, not as parameter semantics. It adds no meaning beyond the schema, 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?

The description uses a specific verb and resource: 'Fetches one thread with its full message list', which clearly identifies what the tool does and distinguishes it from single-message or list tools. It even names the sibling for single messages, making the scope concrete. This is a purpose statement that needs no inference.

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 tells when to use this tool versus an alternative: use this for a full thread with messages, and 'For a single message use get_agentmail_inbox_message'. This provides a clear selection rule rather than leaving the agent to compare schemas.

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/idempotentHint annotations, the description discloses that the download_url is short-lived with expires_at, that bytes are not inlined, and that the URL must be fetched before expiration. This is valuable behavioral context that is not available from annotations alone.

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 sentences, no filler: action and return fields come first, followed by the expiration caveat, the source of IDs, and the sibling pointer. Every sentence earns its place and the information is front-loaded.

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 return format is already documented; the description covers the tool's distinguishing scope, the short-lived download behavior, and the related sibling tool. Nothing essential is missing for correct 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?

Schema coverage is 100% and each parameter is described, so the baseline is 3. The description adds meaning by explaining that IDs come from the thread's attachments array on get_agentmail_inbox_thread, clarifying the relationship between thread_id and attachment_id beyond the generic 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–resource pair: 'Fetches metadata for one attachment anywhere in a thread,' and lists the exact returned fields. It distinguishes itself from the message-level sibling by naming it directly, so an agent can tell this tool apart from alternatives without guessing.

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 context: IDs come from the thread's attachments array, and the message-level twin is explicitly named. It does not state explicit when-to-use versus when-not-to-use conditions, but the source-of-IDs guidance and sibling pointer make the intended usage 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 signal read-only, idempotent, non-destructive behavior; the description goes further by explaining newest-first ordering, pagination via next_page_token, thread/message grouping, and the summary fields returned. 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?

The description is front-loaded with the core action, quickly covers the key behavioral details, and closes with routing to alternatives. No filler; each sentence contributes distinct value.

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 read-only, 12-parameter list operation with a full output schema, the description sufficiently covers scope, ordering, pagination, grouping semantics, and alternatives. Remaining details are already carried by the input schema and 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?

Schema coverage is 100%, so parameters are already documented. The description adds useful meaning around pagination (returned next_page_token for subsequent calls), default ordering (newest first, relevant to the ascending parameter), and the semantic difference between paging and searching.

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 ('Lists'), resource ('conversation threads'), and scope ('in one inbox'), along with default ordering ('newest first'). This clear scope distinguishes it from sibling tools like get_agentmail_threads and get_agentmail_inbox_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?

Explicitly says to use get_agentmail_inbox_messages when individual messages are needed and get_agentmail_inbox_threads_search when querying rather than paging. The description leaves no ambiguity about when this page-oriented, thread-list tool is appropriate.

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, openWorldHint, and non-destructive, so the safety profile is covered. The description adds useful operational behavior beyond that: it discloses pagination behavior (returns count, limit, next_page_token, threads; page with next_page_token) and aligns thread fields with a known sibling tool, setting accurate expectations for the response shape.

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 with no filler: the primary action is front-loaded, followed by pagination/return details, and then sibling routing. Every sentence earns its place and no guidance is buried.

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 exists and annotations carry the safety profile, the description covers the operational essentials: scope to one inbox, pagination flow, return field names, and how to differentiate from sibling search/listing tools. Nothing needed to call it correctly appears 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%, so the schema already documents q's matching behavior, before/after timestamps, limit, page_token, inbox_id, and Authorization. The description adds no parameter-level detail beyond what the schema provides, 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?

The description opens with 'Full-text search across one inbox's threads,' giving a specific verb (search), resource (threads), and scope (one inbox). It also distinguishes itself from siblings by naming get_agentmail_inbox_threads for date-ordered access and get_agentmail_inbox_messages_search for message-level search, so an agent can select the correct tool without inspecting schemas.

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 says get_agentmail_inbox_threads is 'the one to use for everything in date order' and points to get_agentmail_inbox_messages_search when searching individual messages rather than conversations. This gives explicit when-to-use versus alternative guidance beyond what annotations provide.

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, openWorld, idempotent, and non-destructive behavior. The description adds useful context: pagination via next_page_token, the returned entry fields, and the cross-caller reach of the operation. There is 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?

The description is front-loaded with the core purpose and each sentence contributes scope, parameter, return format, or differentiation information. It is slightly longer than strictly necessary, but it does not waste 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?

For a read-only list tool with an output schema and rich annotations, the description is complete: it covers account-wide versus inbox-scoped semantics, pagination, return fields, and the relevant sibling tool. Nothing essential for correct invocation 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 does add conceptual meaning by explaining direction and type in the list context. However, its 'inbound or outbound' phrasing glosses over the schema's send/receive/reply enum, so it does not substantially improve on 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 precise verb and resource: it lists account-wide allow/block list entries. It explicitly names the account scope and contrasts itself with the inbox-scoped twin get_agentmail_inbox_list_entries, so an agent can distinguish it from siblings without inspecting schemas.

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 clearly states that this is the organization-wide view spanning every inbox, notes that every AIsa caller shares one account, and explicitly directs agents to the inbox-scoped sibling when a single inbox is intended. This is concrete when-to-use and alternative 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context on top: `read_only` entries are platform-managed and cannot be deleted, and the account-wide scope can surface entries from inboxes other callers created. No contradiction with annotations is present.

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 and front-loads the core purpose and returned fields before caveats. There is slight redundancy between 'organization-wide view spanning every inbox' and 'reaches inboxes other callers created,' but overall it is efficient and free of 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 read-only annotations, fully documented schema, presence of an output schema, and a description that covers scope, shared-account implications, and the precise sibling to use instead, an agent has all the information needed to decide and invoke correctly. No critical gap stands out.

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 baseline is 3. The description lists output fields like `entry_type` and `list_type` but does not add new meaning about the four required input parameters themselves; it neither clarifies nor repeats what the schema already documents.

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, 'Fetches one account-wide allow or block entry,' and enumerates the exact fields returned. It explicitly contrasts itself with the inbox-scoped sibling, so an agent can disambiguate the two list-entry getters without opening their schemas.

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 this is the organization-wide view spanning every inbox, warns that it reaches entries created by other callers in the shared AgentMail account, and names the alternative tool (`get_agentmail_inbox_list_entry`) to use when a single inbox is intended. This is clear, actionable 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 already declare readOnlyHint and idempotentHint, so the safety bar is lower, but the description adds real behavioral context beyond those flags: empty arrays mean no activity, not error; the key list is not closed and must be read from the response; and the query reflects live organizational-wide state across all inboxes in a shared account.

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 longer than average, but almost every sentence adds distinct value: key examples, the empty-array semantics, the unpinned shape warning, and the scope caveat. It loses one point for slight redundancy between 'organization-wide view spanning every inbox' and the following 'reaches inboxes other callers created' sentence, which could be tightened.

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 metrics tool with a rich output schema and high schema coverage, the description fully covers what an agent needs to call it correctly: what it returns, the meaning of empty data, the non-fixed key set, the shared-account scope, and the explicit routing to the sibling when inbox-level metrics are needed.

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 seven parameters including start/end/limit/period/descending/event_types. The description adds useful context about the return shape and metric key names but does not need to explain parameters any further; the 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 opens with a specific verb and resource: 'Returns aggregate counters for the whole account as a flat map of counter name to an array of data points.' It clearly differentiates itself from the inbox-scoped sibling by naming the twin explicitly and drawing the account-vs-inbox distinction.

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 the alternative: 'the inbox-scoped twin `get_agentmail_inbox_metrics` is the one to use when a single inbox is meant.' It also warns that the shared account means this reaches inboxes other callers created, giving concrete guidance about side effects of 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the cross-account resolution behavior, the fact that a thread id not owned by the caller still resolves, and the instruction to check the returned inbox_id. This is meaningful additional transparency.

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 compact and front-loaded with the core behavior, then lists the returned fields, then explains the cross-account caveat and names the sibling. Every sentence earns its place. It is slightly dense with the field list, but that list is useful for an agent deciding whether this tool returns what it 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?

The tool has an output schema, so return values are already documented. The description covers the key contextual gap: the whole-account resolution and the shared-account caveat. It also names the scoped alternative. It does not mention pagination or message ordering, but for a single-thread fetch with an output schema, the description is sufficiently 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?

Schema description coverage is 100%, so the schema already documents both parameters (thread_id and Authorization). The description adds context about what fields the thread includes and the cross-account behavior, but it does not add syntax or format details for the parameters themselves. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 ('Fetches'), a specific resource ('one thread by id'), and a distinctive scope ('without naming an inbox... resolves against the whole account'). It also names the scoped twin, get_agentmail_inbox_thread, which distinguishes it from the many sibling thread tools. This is a clear, differentiating definition.

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 explains when to use this tool: when you have a thread id and no inbox context, because it resolves across the whole account. It also warns that other callers' threads are reachable and advises checking the returned inbox_id. It names the alternative (get_agentmail_inbox_thread) as the scoped twin, giving the agent a clear routing decision.

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 readOnly, idempotent, and openWorld hints. The description adds valuable context: the bytes are not inlined and the `download_url` has a short expiry, and it clarifies the scope reaches all inboxes due to a shared account. 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?

The description is front-loaded with the core action, then explains the scope and the twin. Each sentence adds a distinct piece of information—return fields, expiration, scope, and alternative—with no filler or 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?

It fully covers what the tool returns, the critical download_url expiration behavior, the scope across all inboxes, and the alternative for inbox-scoped use. With an output schema present, return values are already documented, so nothing needed by an agent 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% and each parameter already has a description. The description adds only that the thread is 'addressed by id alone', which is implied by the schema. It does not add format or syntax details 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?

The description states a specific verb ('Fetches') and resource ('metadata for one attachment in a thread') and explicitly differentiates from the sibling by noting it's the organization-wide view vs the inbox-scoped twin. This makes it unambiguous which tool to pick even without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative `get_agentmail_inbox_thread_attachment` and gives the condition for choosing it ('when a single inbox is meant'), plus explains the shared-account caveat. It also advises to fetch `download_url` before it expires, which is actionable usage 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 already cover the safe read-only, idempotent, non-destructive profile. The description adds meaningful behavioral context: it spans every inbox in a shared account, includes pagination details (next_page_token), and enumerates the return fields, going beyond what annotations 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?

The description is information-dense and well-structured: purpose first, then return shape and pagination, then scope caveat and sibling routing. It is slightly long but every sentence earns its place; 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 tool's complexity (11 params) and the existence of an output schema, the description fully equips an agent to call it correctly: it explains the scope, pagination, return fields, and the critical sibling distinction. Nothing essential 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%, so all parameters are already documented. The description only adds the pagination token context and the field list, which aligns with the output schema but does not enrich parameter meaning beyond what the schema provides.

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 clear verb+resource: 'Lists conversation threads across every inbox in the account.' Explicitly distinguishes from the inbox-scoped sibling get_agentmail_inbox_threads by naming the organization-wide scope and the alternative for single-inbox use.

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 routing guidance: 'the inbox-scoped twin get_agentmail_inbox_threads is the one to use when a single inbox is meant.' Also warns that this reaches inboxes other callers created, which informs when to avoid it for isolated operations.

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 mark the operation as read-only and idempotent. The description adds valuable behavioral context: the returned response fields, pagination behavior via next_page_token, and the important shared-account consequence that the search reaches inboxes created by other callers.

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 action and return shape. It is slightly repetitive ("every inbox in the account" and "organization-wide view spanning every inbox"), but every sentence adds useful routing or behavioral context.

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 description covers the tool's scope, response fields, pagination behavior, and sibling-tool distinctions. Combined with the rich schema and annotations, an agent has everything it needs to invoke 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 input schema already provides full descriptions for all parameters, including the q query semantics and pagination token. The tool description adds little parameter-specific detail beyond mentioning pagination, so the schema-coverage 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 performs full-text search over threads in every inbox in the account. It also distinguishes itself from sibling tools like get_agentmail_threads and get_agentmail_inbox_threads_search, making selection 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?

Explicitly names when to use this tool versus alternatives: get_agentmail_threads for date-ordered listing, get_agentmail_inbox_threads_search for single-inbox searches, and this tool for organization-wide search across all inboxes. This leaves no ambiguity about the intended use case.

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. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

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 moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not 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?

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use it 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 parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

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 purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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 implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, not stated.

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. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

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 moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

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 zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap for an agent to call it 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 tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics gap.

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 what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

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 usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling 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?

Beyond annotations (destructiveHint, openWorldHint), the description discloses the shared multi-caller workspace, that writes reach inboxes other callers created, that changes are visible/editable by later callers, and that the return value is the full updated inbox. It also notes the address is immutable. 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?

Four tight sentences put the core mutation first, then return value, then shared-workspace warning, then read alternative. Every sentence earns its place and the most important behavioral caveat is front-loaded.

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 mutating inbox tool with an output schema and rich parameter schema, the description covers purpose, return value, cross-caller side effects, and the safe read alternative. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with rich descriptions of display_name and metadata merge/null behavior, so the description doesn't need to re-explain parameters. It adds the high-level field scope and address-immutability note, but no per-parameter detail; 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?

Starts with the specific verb 'Updates' and names exactly the resource and fields ('one inbox's display_name and metadata'), and explicitly states the address cannot change. This distinguishes it from sibling patch/draft/message/thread tools and from get_agentmail_inbox, so 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?

Provides clear usage context: this is the write path for inbox display_name/metadata, while 'To read without changing anything use get_agentmail_inbox' gives an explicit alternative. It warns about shared-workspace side effects, but it does not explicitly contrast with patch_agentmail_inbox_draft/thread/message; the resource-scoped naming and wording handle that indirectly.

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 mark destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds valuable context: the shared workspace side effect (visible/editable by other callers) and the fact that it does not send. It also mentions returning the full draft. However, it does not clarify partial-update semantics (whether omitted fields are preserved or cleared), which is a meaningful behavioral gap for a patch operation.

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 the core action front-loaded and no filler. The shared-workspace note is placed at the end, which is acceptable. The slight inaccuracy regarding 'attachments' prevents a perfect score.

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 exists, so return values need not be detailed beyond the description's 'returns the full draft' statement. The shared-workspace and non-sending context are useful. However, the description omits partial-update semantics (critical for a patch tool) and includes an inaccurate 'attachments' reference, leaving an agent uncertain about field preservation. Overall, adequate but with notable gaps.

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 parameters are fully described in the schema, earning a baseline of 3. The description's generic reference to 'recipients, subject, body' adds little beyond what the schema already provides, and the mention of 'attachments' is misleading since no such parameter exists. It does not compensate for the gap in 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?

States a specific action ('Rewrites an unsent draft's recipients, subject, body or attachments') and identifies the resource clearly. It also distinguishes from sending by naming the sibling tool. However, it mentions 'attachments' which do not appear in the schema, creating a minor inaccuracy.

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 tells the agent when not to use it ('Still sends nothing') and names the alternative for sending. It also provides context about the shared workspace, which informs usage. It does not contrast with draft creation (post_agentmail_inbox_draft), but the purpose is clear enough.

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 and openWorldHint, and the description adds meaningful context about the shared AgentMail workspace: writes affect inboxes other callers created and are visible/editable to future callers. It also clarifies that only labels are mutable and describes the return payload. No contradiction with annotations is present.

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 with no filler. It front-loads the operation and result, then adds the shared-workspace warning, then provides a read alternative. Every sentence contributes necessary 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?

The description covers purpose, return value, shared-workspace side effects, and the read alternative, and the output schema handles return details. The main gap is that neither the schema nor the description states that at least one of add_labels or remove_labels must be provided for the call to be meaningful.

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 parameters. The description adds that the operation applies to 'one message' and that labels are the mutable field, but it does not explain the relationship or precondition between add_labels and remove_labels beyond what the schema provides. A 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 specific action ('Adds or removes labels on one message') and the resource ('labels' on a message), and explicitly mentions the return value. It also distinguishes this tool from sibling patch tools by noting that labels are the only mutable part of a received 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?

The description provides clear context for when to use the tool: modifying labels on a received message. It also points to get_agentmail_inbox_message for reading current labels and notes that labels are the only mutable part, implying other mutation tools handle other resources. However, it does not explicitly enumerate alternative patch tools for drafts or threads.

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 destructive and open-world behavior, but the description adds high-value context: the shared AgentMail workspace means writes affect other callers' inboxes and are visible/editable by the next caller. It also discloses the resulting labels in the return and that the operation applies thread-wide. This goes well beyond the annotation flags.

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 action and return, the second clarifies scope and names the alternative, the third warns about shared state. Information is front-loaded and no filler is present.

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 description covers the core action, return value, thread-wide scope, the per-message alternative, and the critical shared-workspace side effect. It does not clarify how this tool differs from `patch_agentmail_thread`, which is a similarly named sibling. That minor gap prevents a perfect score.

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 each parameter (add_labels, remove_labels, inbox_id, etc.). The description adds only a general statement about adding/removing labels, not new parameter-level meaning. 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 opens with a specific verb-resource pair: 'Adds or removes labels on a whole thread' and immediately states the returned values. It explicitly names the per-message twin `patch_agentmail_inbox_message`, making the scope clear. This distinguishes it from both the per-message patch and other thread operations in the sibling list.

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 clearly says this applies to every message in a thread at once and points to `patch_agentmail_inbox_message` for per-message granularity. However, it does not address the closely named sibling `patch_agentmail_thread`, leaving potential confusion about when to use the inbox-scoped variant versus the non-inbox variant. Context is solid but exclusions are incomplete.

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 destructive/shareworld behavior, but the description adds essential context beyond them: writes reach inboxes created by other callers and are visible/editable by the next caller. This shared-workspace caveat is exactly the kind of behavioral nuance that annotations alone do not communicate.

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 three-sentence structure front-loads the core action, then adds scope/warning, then the sibling pointer. It is efficient, though the shared-workspace sentence is a bit long and could be trimmed without losing meaning. Overall it 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 write tool with 4 params, full schema coverage, an output schema, and annotations, the description covers the key behavioral, scoping, and alternative-selection aspects. It doesn't repeat schema details (like system-label restrictions) but conveys all necessary context for correct 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by saying the thread is addressed 'by id alone' and that no inbox is named, clarifying that `thread_id` is globally sufficient and there is no inbox parameter. This goes slightly beyond the schema's plain 'ID of thread'.

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+resource: 'Adds or removes labels on a thread addressed by id alone.' It also clearly distinguishes this tool from the scoped twin (`patch_agentmail_inbox_thread`) by stating that it resolves account-wide, so an agent can immediately understand its unique role among siblings.

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 names the alternative ('The scoped twin is `patch_agentmail_inbox_thread`') and gives the condition for choosing this one: no inbox is named, so it resolves account-wide. This provides a clear when-to-use vs. alternative contrast without requiring extra 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 readOnlyHint=false and destructiveHint=true; the description does not contradict them. It adds valuable behavior beyond the flags: writes go to a shared AgentMail workspace visible and editable by other callers, created inboxes are real send/receive addresses, and usernames may be generated.

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 each sentence adding a distinct piece of information: creation semantics, username behavior, domain restriction, return values, workspace sharing, and follow-up tools. It is longer than a minimal description, but the extra length is justified by the shared-workspace warning and parameter nuances.

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 full schema coverage, rich output schema, and meaningful annotations, the description covers everything an agent needs to call this safely: what creation does, how addresses are generated, the shared-state side effect, and how to verify the result. No critical usage or behavioral context 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 semantic value for username and domain: it explains the local-part behavior with examples and states that the domain is always agentmail.to because domain management is not exposed. Other parameters are adequately covered by 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 'Creates a new inbox — a real address that can send and receive,' giving a specific verb, resource, and capability. The 'real address' framing clearly distinguishes it from draft-only tools, and the domain/username details further narrow the purpose.

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 useful usage guidance: how to choose a username, that the domain is fixed to agentmail.to in this context, and which read/list tools to use afterward. It does not explicitly say when to prefer this tool over post_agentmail_inbox_draft or patch variants, but the core usage 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 indicate readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds valuable context: that the draft is staged without sending, that the shared workspace is visible/editable by other callers, and that the operation is safe because it doesn't send. It also clarifies the return includes draft_id. This goes beyond annotations without contradicting them.

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 two sentences, with the purpose front-loaded. The second sentence is longer but packed with essential context about shared workspace and safety. No filler or redundant information; every part 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?

Given the output schema exists (it returns the full draft), the description covers the key aspects: purpose, usage context, behavioral nuances, and parameter semantics. It lacks nothing an agent needs to correctly decide when to use this tool and what to expect.

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 each parameter already has a description. The tool description adds semantic value by grouping key parameters (to, cc, bcc, etc.) and explaining that in_reply_to/references are for threading. This provides contextual understanding beyond the schema's individual definitions.

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 verb 'composes' and the resource 'a draft in one inbox', and explicitly differentiates from the send tool by noting nothing leaves the account until the send endpoint is called. It also distinguishes from other sibling tools like patch or delete by focusing on creation without sending.

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: to stage outbound mail for review, and mentions the alternative send tool by name (post_agentmail_inbox_draft_send). It also warns about the shared workspace, indicating caution for other callers. This gives clear guidance on selection.

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' destructiveHint=true, the description adds critical behavioral detail: the email cannot be recalled, the call sends the draft's current contents rather than any new content, and all AIsa callers share one account so the email can reach message and thread state created by other callers. This materially helps an agent understand real-world side effects.

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 compact and front-loaded with the core action and return values, followed by essential warnings. Every sentence adds value, though the warning section is slightly wordy with the emoji and the shared-account note combined.

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 destructive, non-idempotent send operation with an output schema and 100% parameter coverage, the description is complete. It provides the return values, the prerequisite review step, the irreversible nature of the action, and the shared-account caveat. Nothing essential is missing for correct 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?

Schema description coverage is 100%, so the baseline is 3. The description adds no specific parameter-level meaning beyond noting that the call has no content of its own, which indirectly clarifies why send-related content parameters are absent. The parameter meanings themselves are already adequately documented in 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: sending an existing draft and returning `message_id` and `thread_id`. It also distinguishes itself from other send-like siblings by emphasizing that it takes no content of its own and sends whatever the draft currently holds.

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 usage context: review the draft with `get_agentmail_inbox_draft` first, and only send when the draft is ready. It does not explicitly name alternative send tools or state when not to use them, but the 'takes no content of its own' phrasing makes the intended workflow reasonably clear.

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