machine-inbox

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

No annotations are provided, so the description carries the full burden. It discloses critical behavioral traits: the out-of-band payment process (Stripe or USDC), the return of a live HTTP 402 challenge, and the cost ($2.00). It does not detail idempotency key behavior or error states, but the core mutation and payment flow are transparent.

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 deliver complete intent, payment process, and cost. Every word is purposeful; the description is front-loaded with the primary action. 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?

For a simple tool with a single parameter and no output schema, the description covers return value (HTTP 402 challenge plus instructions) and key constraints (payment out-of-band). Missing details like idempotency retry behavior or error handling are minor gaps, but overall sufficient for an agent to invoke 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 coverage is 100% with a clear description of the idempotency_key parameter. The description adds no additional meaning about this parameter beyond what the schema already provides. Baseline 3 is appropriate per guidelines.

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 'Request a new paid inbox' with a specific verb and resource. It distinguishes itself from sibling tools like delete_inbox and get_inbox by specifying the paid nature and unique return of a payment challenge, leaving no ambiguity about its function.

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 creating a paid inbox and details the payment flow, but it does not explicitly state when to avoid this tool or recommend alternatives. Sibling tools exist (e.g., get_inbox for existing inboxes), but no direct comparison is provided, leaving the decision partially to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly communicates the two irreversible effects: token revocation (breaking access) and data erasure. This is sufficient to warn an agent that the operation is destructive, though it could further emphasize that the deletion is permanent and cannot be reversed.

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

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

The description is a single, front-loaded sentence that wastes no words. Every part is meaningful: the action ('delete'), the resource ('inbox'), and the specific effects ('revokes token and erases stored mail'). It is perfectly sized for efficient comprehension.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is nearly complete. It lacks explicit mention that the operation is permanent, but the given effects ('erases stored mail') strongly imply irreversibility. The only minor gap is not explicitly stating that there is no confirmation step or undo.

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 value beyond the schema by explaining the consequences of using the required parameter (inbox_id) and the optional token parameter (tied to authentication context). This helps an agent understand the practical meaning of each parameter.

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 verb 'delete' and resource 'inbox', and further clarifies the precise actions taken: token revocation and erasing stored mail. This action is distinct from all sibling tools (create, get, list, reply_to, etc.), eliminating any ambiguity.

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 this is a destructive action by mentioning 'revokes' and 'erases', which guides appropriate use. However, it does not explicitly state when not to use it or mention alternatives (e.g., no undo), leaving some gap for an AI agent to infer caution on its own.

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?

No annotations are provided, so the description must convey behavioral traits. The description does not mention whether this is destructive or requires specific authorization (e.g., token vs. bearer header). The parameter descriptions hint at authentication, but the description itself lacks explicit behavioral guidance. It is a simple read operation, so a score of 3 is reasonable.

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

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

The description is a single concise sentence that lists the key attributes returned. It could be slightly more structured (e.g., use a colon or bullet points), but it is efficient and 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?

Given there is no output schema and no annotations, the description is minimal but covers the core purpose. However, for a simple read operation with only two parameters and a straightforward return of five listed fields, the description is adequately complete. There is no indication of pagination or complex behavior 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 both parameters well. The description does not add any new meaning beyond what is in the schema, so the baseline score of 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 uses the specific verb 'Read' and resource 'inbox' and lists the concrete attributes returned (address, status, expiry, limits, usage), making the tool's purpose very clear and distinguishing it from sibling tools like create_inbox or list_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?

The description implies this is a read operation to fetch inbox details, and the context of sibling tools like create_inbox and delete_inbox helps differentiate. However, there is no explicit statement about when to use this tool versus alternatives or when not to use it (e.g., if you only need the verification code, use get_verification_code instead).

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?

No annotations are provided, so the description must fully disclose behavioral traits. It states the tool fetches a message and returns specific content, but it does not mention whether the operation is read-only, any authorization requirements beyond the token parameter, rate limits, or side effects. The description lacks essential transparency for a tool with no annotations.

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

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

The description is a single sentence of 11 words, starting with the imperative verb 'Fetch'. Every word is necessary and contributes to understanding the tool's function. There is no redundancy or extraneous 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?

Given no output schema, the description lists key return elements (parsed text, HTML, attachment download URLs) but does not specify whether additional fields like sender or subject are included. It also fails to mention error conditions or how to use the download URLs. While the core functionality is communicated, gaps remain for a fully self-contained description.

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

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

The schema covers 67% of parameters with descriptions (token and inbox_id), but message_id has no description. The description adds no additional parameter information beyond stating what the tool returns. It does not explain the purpose of message_id or elaborate on token usage, failing to compensate for the incomplete 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 clearly states the tool fetches a single message and returns parsed text, HTML, and attachment download URLs. This distinguishes it from siblings like list_messages (which returns multiple) and get_inbox (which returns inbox metadata). The verb 'Fetch' and resource 'one message' are 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 this tool is for retrieving a single message's details, but it does not explicitly state when to use it over alternatives such as list_messages or get_inbox. No exclusions or context on when not to use it are provided. The usage context is clear but not compared to siblings.

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?

With no annotations, the description bears the full burden of behavioral disclosure. The word 'Read' implies a read-only, non-destructive operation, which is appropriate. However, the description does not explicitly state that the tool is side-effect-free, idempotent, or whether it requires authentication. The behavioral traits are minimally conveyed but not exhaustive.

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

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

The description is a single sentence of 13 words, front-loading the verb and resource. Every word adds value: 'Read' specifies the action, 'Machine Inbox service instructions' names the resource, and the colon introduces the listed content categories. No redundant or unnecessary information 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?

Given the tool's simplicity (no parameters, no output schema, no annotations), the description is complete. It tells the agent what the tool does (reads service instructions) and what it returns (pricing, payment rails, endpoints, limits). There is no ambiguity about the tool's purpose or output, making it self-sufficient for a simple info retrieval 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?

The tool has zero parameters, and the schema coverage is trivially 100%. According to the guidelines, baseline is 4 when there are no parameters. The description does not add parameter details because there are none, but it does not need to. The content categories listed in the description serve as implicit output context, not 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 the tool reads 'Machine Inbox service instructions' and lists specific content categories (pricing, payment rails, endpoints, limits). The verb 'Read' combined with the resource 'service instructions' makes the purpose unambiguous. It is easily distinguished from sibling tools which handle inbox operations like create, delete, or message retrieval.

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 does not provide any guidance on when to use this tool versus alternatives. It fails to mention that it should be used for obtaining service-level configuration rather than individual inbox or message data. No exclusions, prerequisites, or references to sibling tools are included.

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 indicates read-only behavior (extract from mail, newest) without annotations. It does not disclose important traits like whether the operation consumes/destroys the code, authentication requirements beyond the token parameter, or what happens if no code is found. With no annotations, the description carries the full burden and provides only basic 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?

Two sentences: first states the core action and object, second gives ideal use cases. Extremely concise, front-loaded, and every word earns its place. No redundancy or irrelevant details.

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 3 parameters (1 required), no output schema, and no annotations, the description explains the tool's unique purpose versus siblings (e.g., get_message). However, it does not specify what the tool returns (the code/link text? the full message?) or behavior on failure (e.g., no verification code found). Mostly complete but could clarify return format.

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, so baseline is 3. The description adds purpose context (e.g., 'newest verification code') but does not elaborate on parameter semantics beyond what the schema already provides (token optional, sender filter, inbox_id required). No additional value given.

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 ('Extract') and a clear resource ('one-time verification code or confirmation link from inbound mail'). It distinguishes itself from siblings like get_message and list_messages by focusing on extraction of a specific type of content (codes/links) from mail, and specifies 'newest' which adds precision.

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

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

Explicitly states 'Ideal for signup and login flows,' providing clear context for when to use it. However, it does not explicitly exclude other scenarios or mention alternatives (e.g., use get_message for full message retrieval), but the sibling context makes such distinctions implicit.

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?

With no annotations, the description carries the full burden. It discloses ordering and polling behavior but omits pagination details (e.g., how limit and before interact, whether token is for pagination or auth), error behavior, and authentication requirements beyond the token parameter. The description is adequate for basic use but leaves gaps.

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, front-loaded with the core purpose, then a specific usage hint. No wasted words; every sentence earns its place. The structure supports quick comprehension.

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 has 5 parameters, no output schema, and no annotations, the description covers only the basic purpose and one usage pattern. It does not explain pagination (limit, before, token behavior) or return format, leaving the agent under-informed for non-polling scenarios. Adequate but not comprehensive.

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 80%, so most parameters are already described. The description adds value beyond the schema by explaining how to use 'after' for polling ('Pass after=<newest createdAt seen>'). This practical guidance enhances the agent's understanding without repeating schema content.

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 'List messages in an inbox, newest first,' which uses a specific verb ('List') and resource ('messages') with ordering. This distinguishes it from sibling tools like get_message (single message) and create_inbox (different operation).

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 a concrete usage pattern for polling ('Pass after=<newest createdAt seen> to poll for only new mail'), giving clear context for one common scenario. However, it does not explicitly exclude other tools or state when to use this tool versus alternatives like get_message, leaving some inference needed.

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?

No annotations are provided, so the description carries full burden. It states that the reply is 'plain-text' and sent to the 'authenticated sender', which implies authorization context. However, it does not disclose side effects (e.g., does it mark the message as replied? Is the reply visible elsewhere?), potential rate limits, or whether the operation is destructive. It is clear but not comprehensive.

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

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

The description is a single, compact sentence that front-loads the action and key constraints. Every word serves a purpose, and there is no redundancy. It could be slightly more concise by removing 'included' (the inclusion is implied), but overall it is well above average.

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 5 parameters (60% schema coverage), no output schema, and no annotations. The description is functional but lean. It explains the core action but omits important contextual details like return value (is there a confirmation ID?), error scenarios (e.g., invalid inbox_id), or idempotency behavior beyond the schema hint. For a tool with moderate complexity, it meets a minimum viable level but leaves 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 description coverage is 60%, with fields like `text`, `token`, `inbox_id`, and `idempotency_key` having descriptions in the schema. The description adds little beyond, only mentioning 'plain-text' for the reply content. For `message_id`, the description does not help clarify what this refers to, and the schema lacks a description for it. The overall added value from the description is marginal.

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 ('Send') and identifies the resource ('plain-text reply' directed at the 'authenticated sender of an inbound message'). This clearly distinguishes it from sibling tools like create_inbox or list_messages, as it is the only tool focused on sending a reply to a message sender.

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 implicitly states when to use the tool (when you need to reply to an inbound message), but it provides no explicit guidance on when not to use it, nor does it mention alternatives. Sibling tool names like get_message or list_messages hint at possible related actions, but no direct comparison or exclusion is given.

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