agentmail

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

While annotations indicate this is a write operation (readOnlyHint: false) and non-idempotent, the description adds no behavioral context. It doesn't explain failure modes (e.g., if username@domain already exists), side effects, or whether the created inbox is immediately usable.

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?

Extremely brief at two words, but this is under-specification rather than efficient conciseness. For a mutation tool with 3 parameters and no output schema, the description fails to earn its place by conveying essential information upfront.

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?

Inadequate for a creation mutation. Missing: return value description (does it return the inbox ID?), relationship between parameters (is username@domain the address?), and implications of all parameters being optional. Sibling tools suggest email functionality, but this isn't confirmed.

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 has 100% description coverage with basic labels ('Domain', 'Username'). The description adds no parameter semantics, but baseline is 3 since schema coverage is high. No explanation of how domain+username combine or why all 3 parameters are optional for a creation operation.

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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives. Missing prerequisites (e.g., domain verification requirements), uniqueness constraints, or when to use send_message directly without creating an inbox first.

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?

While annotations correctly indicate destructiveHint=true and idempotentHint=true, the description adds no behavioral context beyond what the name implies. It fails to disclose what happens to contained messages/threads or whether deletion is recoverable.

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?

At two words, it is brief, but this represents under-specification rather than efficient conciseness. The single 'sentence' merely echoes the tool name and earns no informational 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 destructive operation with no output schema, the description is inadequate. It omits critical context about cascade effects on messages, recovery options, or required permissions that would help an agent assess invocation risks.

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% (inboxId is documented), establishing baseline 3. The description itself mentions no parameters, but no additional compensation is needed given the complete schema 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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives, prerequisites (e.g., emptying the inbox first), or warnings about permanent data loss despite the destructiveHint annotation.

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?

While the description does not contradict annotations (it implies a write operation consistent with readOnlyHint=false), it adds zero behavioral context beyond what annotations provide. It fails to explain whether forwarding creates a new message, preserves attachments automatically, or requires manual inclusion of original content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Although only two words, the description is not effectively concise because the content earns no value—it merely duplicates the title. It lacks front-loaded critical information or structural organization.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters including nested attachment objects) and lack of output schema, the description is grossly incomplete. It fails to explain forwarding mechanics, return values, or the relationship between html/text body parameters.

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?

With 100% schema description coverage, the structured schema already documents all 10 parameters adequately. The description adds no parameter-specific guidance, but the baseline score of 3 applies per rubric guidelines 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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives (send_message, reply_to_message) or prerequisites for use. The description offers no 'when-to-use' or 'when-not-to-use' 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?

While the description doesn't contradict the annotations (readOnlyHint: true aligns with 'Get'), it adds zero behavioral context beyond what annotations provide. It omits what the return format is (binary, base64, URL?), potential size limits, or implications of openWorldHint: true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

At two words, this is under-specification masquerading as conciseness. There is no information to front-load; the description fails to earn its place by providing any actionable context to the agent.

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 no output schema and three required parameters, the description should explain what the tool returns (raw bytes, object metadata, download URL?). It provides no such information, leaving the agent uncertain about the result structure.

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% (all three parameters have descriptions), establishing a baseline of 3. The description adds no additional parameter guidance (e.g., ID formats, examples), but the schema carries the full load adequately.

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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives, nor any mention of prerequisites (e.g., that the inbox and thread must exist first). The description lacks any 'when-not-to-use' or workflow 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?

While annotations declare readOnlyHint=true (confirming this is a safe read operation), the description adds no behavioral context about what data is returned, pagination, or authentication requirements. It meets the lower bar set by annotations but provides minimal additional value.

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?

Though brief (two words), this represents under-specification rather than effective conciseness. The single sentence fails to earn its place by providing actionable information beyond the tool name itself.

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 sibling list_inboxes and the requirement for a specific inboxId, the description should clarify this retrieves a single specific inbox versus listing all. Without an output schema, the description misses the opportunity to hint at return structure.

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?

With 100% schema description coverage (inboxId is described as 'ID of inbox'), the schema carries the full burden. The description adds no supplemental context about the parameter format or where to obtain the ID, warranting the baseline score for high-coverage 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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus list_inboxes, nor any mention that inboxId must be obtained beforehand (likely from list_inboxes). No prerequisites or exclusions are 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?

While annotations declare readOnlyHint=true and openWorldHint=true, the description adds zero behavioral context beyond these structured hints. It does not describe what data structure is returned, pagination behavior, or the scope of 'openWorld' access in this domain.

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?

Though only two words, this represents under-specification rather than efficient conciseness. The single sentence earns no informational value, failing the 'every sentence should earn its place' standard as it provides no content beyond the tool identifier.

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 absence of an output schema, the description should explain the return value (thread object structure, message contents, metadata). It also fails to clarify the domain relationship between threads, messages, and inboxes evident in the sibling tools. Minimal viable information 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?

With 100% schema description coverage ('ID of inbox', 'ID of thread'), the parameters are already documented. The description adds no additional semantic context (e.g., format expectations, where to obtain these IDs), warranting the baseline score for high-coverage 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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives like list_threads. No mention of prerequisites (e.g., needing to obtain threadId from a previous list operation) or error conditions (e.g., thread not found).

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?

While annotations correctly indicate readOnlyHint=true, the description adds no behavioral context beyond the schema. It does not disclose return structure (no output schema exists), pagination behavior, or whether results are ordered/filtered by default.

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?

Though brief (2 words), this represents under-specification rather than efficient conciseness. The single sentence conveys no information not already present in the tool name, failing to earn 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?

Without an output schema, the description should indicate what inbox properties are returned. It also omits scope details (e.g., whether this lists all accessible inboxes or only owned ones) and relationship to the create_inbox/delete_inbox lifecycle.

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 adequately documents limit and pageToken. The description adds no parameter-specific guidance, earning the baseline score for complete 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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives like get_inbox for specific inbox retrieval. No mention of pagination strategy or filtering capabilities.

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 openWorldHint=true, but description adds no behavioral context about pagination behavior, default limit (10), or the fact that results may include external/unexpected data (openWorld). Does not mention temporal filtering capabilities.

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?

Extremely terse (4 words) with zero redundancy. However, excessive brevity given the tool's complexity (6 parameters, pagination, filtering), leaving critical functionality undocumented in natural language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Inadequate for a list operation with temporal filtering, label filtering, and pagination capabilities. No output schema exists, yet description fails to characterize the return structure (array of threads?) or hint at filtering capabilities beyond the basic scope.

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%, establishing baseline 3. Description provides no additional parameter context (e.g., datetime formats for after/before, label syntax, pagination flow), but schema adequately documents all 6 parameters.

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 verb ('List') + resource ('threads') + scope ('in inbox'), but fails to distinguish from sibling 'get_thread' (single retrieval vs. listing) or clarify when to use this over 'list_inboxes'.

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?

No guidance on when to use this tool versus alternatives. Missing explicit mention that this requires an inboxId (from get_inbox or list_inboxes) and does not cover pagination strategy guidance despite the pageToken parameter.

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?

While annotations correctly indicate this is a write operation (readOnlyHint: false) and not idempotent (idempotentHint: false), the description adds no behavioral context about these traits. It fails to disclose that multiple invocations create multiple replies, or explain the implications of openWorldHint: true for external recipients.

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?

While extremely brief (3 words), this represents under-specification rather than effective conciseness. The single sentence provides no actionable information beyond the tool name itself, failing to earn its place in the definition.

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?

Inadequate for a 7-parameter messaging tool with complex nested attachment objects and no output schema. The description omits critical operational context such as threading behavior, attachment handling limitations, and the non-idempotent nature of the operation despite these being important for correct agent usage.

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?

With 100% schema description coverage, the parameter semantics are fully documented in the schema itself. The description adds no additional parameter guidance (e.g., explaining the mutual exclusivity or precedence of html vs text), but the high schema coverage establishes a baseline of 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?

Tautological: description restates name/title.

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 no guidance on when to use this tool versus send_message or forward_message. Does not explain prerequisites (e.g., requiring messageId from an existing thread) or when to use replyAll versus a standard reply. No mention of html vs text body selection criteria.

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?

While annotations declare readOnlyHint=false and idempotentHint=false, the description adds no behavioral context about what these imply (e.g., that duplicate calls send multiple messages, or that this affects external recipients due to openWorldHint=true). It neither leverages nor contradicts the annotation safety hints, providing zero additional operational 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?

At two words, the description is brief but suffers from under-specification rather than efficient information density. It is not front-loaded with critical behavioral constraints or differentiating details; instead, it provides minimal viable text that forces the agent to rely entirely on schema and title inference.

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 complex 9-parameter composition tool with attachment handling and multiple similar siblings, the description is inadequate. It omits expected behaviors (draft creation vs. immediate send, delivery confirmation, error states) and fails to clarify relationships to the inbox/thread ecosystem despite the rich parameter schema requiring operational context.

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?

With 100% schema description coverage across all 9 parameters including nested attachment objects, the schema carries the full semantic load. The description adds no parameter syntax, format examples, or constraints beyond the schema, warranting the baseline score for comprehensive 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?

Tautological: description restates name/title.

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?

No guidance provided on when to use this tool versus alternatives like 'reply_to_message' or 'forward_message'. No prerequisites mentioned (e.g., requiring an existing inbox from 'create_inbox'), and no conditions for success or failure are described.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false. However, the description adds no behavioral context beyond this, failing to disclose that the update operation modifies labels (add/remove) rather than message content, or what the side effects are.

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?

At two words, the description is under-specified rather than appropriately concise. It fails to earn its place by providing actionable information to the agent, representing a lack of structural content rather than efficient communication.

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 mutation tool with 4 parameters and no output schema, the description is inadequate. While the schema documents parameters well, the description omits critical context about the tool's specific purpose (label management), potential errors, or relationships to sibling operations.

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?

With 100% schema description coverage, the input parameters (inboxId, messageId, addLabels, removeLabels) are fully documented in the JSON schema itself. The description adds no additional parameter semantics, meeting the baseline for high-coverage 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?

Tautological: description restates name/title.

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 no guidance on when to use this tool versus alternatives. It does not clarify that this performs label manipulation (per the schema) versus content editing, nor does it mention prerequisites or constraints.

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