mailbox

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

The description discloses the mutation (advance one lifecycle step), the side effect (queue matching webhook), and the simulated data added at each transition (pages/envelope photos, carrier, dispatch method, receipt photo, tracking conditionally). It does not specify behavior on a terminal state or repeated calls, but annotations already mark it as non-read-only and non-idempotent, and the description adds meaningful detail beyond those 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?

The description is a single dense sentence that front-loads the action and then lists the deterministic state transitions without filler or repeated schema information. Every clause earns its place by describing what happens at each lifecycle stage.

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

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

For a one-parameter stateful test tool, the description covers all lifecycle transitions and the main side effect, and an output schema exists to define the return shape. It omits error handling for invalid states or non-test_mode records, but those are secondary concerns when selecting and invoking 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?

Schema description coverage is 100%, with mail_id already documented as 'UUID of the test_mode outbound mail record to advance.' The description reinforces the same conceptual framing and adds lifecycle context, but it does not add new parameter-level details or syntax, 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?

States a specific verb ('advance'), a specific resource ('test_mode outbound mail record'), and enumerates exact lifecycle transitions (submitted→ready→mailed→delivered). It also discloses the side effect of queueing a matching webhook, which clearly distinguishes it from sibling tools like send_outbound_mail or cancel_outbound_mail.

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

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

The description clearly scopes the tool to test_mode records and defines the state-transition behavior, so an agent can infer when it should be used rather than creation or cancellation tools. It does not explicitly name alternatives or say 'do not use for production mail,' but the test_mode qualifier and sibling names provide adequate directional 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 description substantially exceeds the annotations. While annotations already note idempotentHint=true and destructiveHint=true, the description explains the specific destructive side effect (returning prepaid credits), confirms idempotency ('already-cancelled mail returns cancelled status without creating a duplicate refund'), and adds operational guidance (chat reporting requirements and error polling). This provides context far beyond the boolean hints.

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

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

The description is a single dense paragraph of four sentences. It front-loads the primary purpose, then efficiently covers side effects, idempotency, reporting requirements, and error handling. While it is longer than minimal, every sentence contributes meaningful information, so the length is justified.

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

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

For a tool with one parameter and an output schema, the description is exceptionally complete. It covers the action, timing constraint, side effects, retry behavior, what to report in chat, and how to handle transient errors. There are no significant gaps that would prevent an agent from using 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 fully describes mail_id as 'UUID of the queued outbound mail job to cancel' with 100% coverage. The description does not add additional meaning to the parameter itself, so the baseline of 3 is appropriate. No extra semantics are needed for a single, well-documented 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 action: 'Cancel a queued outbound mail job before facility printing starts.' This specifies the verb 'cancel', the resource 'outbound mail job', and a critical condition ('before facility printing starts'). It distinguishes the tool from siblings like send_outbound_mail (which creates) and get_outbound_mail/list_outbound_mail (which read), by focusing on cancellation of a queued job.

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 usage: it is for cancelling queued mail before printing begins, and it includes retry guidance ('Safe to retry') and error handling ('poll the mail status and credits before retrying'). It lacks an explicit comparison to alternatives, but the condition 'before facility printing starts' and the action 'cancel' make when to use it unambiguous given the sibling set.

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 transparently discloses that no real document is uploaded, that the record is always test_mode=true, that cost_cents will be 0, that estimated live costs and cost breakdowns are included, and that a mail.submitted webhook is queued. This goes beyond the minimal annotations and gives the agent a clear behavioral model.

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 very long and repetitive, with the same color-pricing text appearing multiple times in the schema and again in the description. While it contains useful pricing and behavioral details, it is not concise and could be significantly streamlined without losing essential 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 the tool's purpose, sandbox behavior, cost simulation details, carrier-specific adjustments, and webhook side effects. It is complete enough for an agent to decide when and how to use this tool, though the excessive repetition makes it harder to parse quickly.

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 covers 100% of parameters with descriptions, and the tool description provides additional pricing context. However, the parameter descriptions in the schema are extremely verbose and repetitive, and the tool description adds pricing details that are already embedded in the schema, so the added semantic value is moderate rather than high.

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 action ('Create a sandbox outbound mail record') and clearly distinguishes it from sending real physical mail, explicitly noting it is for rehearsing outbound workflows with a sandbox key. This provides strong purpose clarity and differentiates it from sibling tools like send_outbound_mail.

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

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

The description explicitly says to use this with a sandbox key to rehearse outbound workflows before sending real physical mail, giving clear when-to-use guidance. It does not explicitly enumerate when not to use it versus every sibling, but the sandbox-only framing is sufficient for most agent decision-making.

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

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

Beyond the annotations, the description discloses critical behavioral details: the webhook is active immediately on save, the whsec_ signing secret is returned only once and must be handled securely, idempotency_key reuse is required after uncertain mutations, and authorization follows the same bounded control plane as existing webhook endpoints. These details materially affect how the agent should invoke and handle results.

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 dense paragraph, but every sentence carries material operational or security guidance. It is front-loaded with the core creation action and parameter overview, followed by important caveats. A slightly more structured layout or shorter sentences would improve readability, but nothing is wasted.

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

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

Given seven required parameters, an output schema, and annotations, the description covers all essential context: authentication requirements, scope rules, secret-handling instructions, idempotency behavior, and a link to full documentation. An agent has what it needs to call the tool safely and 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 0%, so the description carries the full burden of explaining parameters. It does so comprehensively: name, public HTTPS URL, event types, rules structure (literal terms, any/all, exclusions), agent_id/environment scoping, and idempotency_key semantics. This adds meaning beyond the raw schema and would allow an agent to construct a correct request.

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 clear, specific verb-resource pairing: 'Create a webhook' and then enumerates the exact fields and event types involved. This makes it immediately distinguishable from sibling update/test/rotate tools without needing to inspect 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 provides strong contextual guidance: it explains when creation is appropriate, emphasizes explicit user intent for the URL, distinguishes agent-key versus member-key scoping, and states the required webhook.manage permission. It does not explicitly name a sibling such as update_webhook_endpoint for modifications, but the create versus update distinction is clear from the tool name and description.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds significant non-obvious context: the scopes required (agent.inbox.read, plus agent.read for sample activity), the agent-scoped bearer key requirement, the semantics of a receipt not being proof of worker compliance, and the fact that rollout/approval/authorization settings are shared with REST. This substantially exceeds annotation-only 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 long but front-loaded with deprecation and replacement, then states the function, parameter, scopes, key requirements, and caveats. Some repetition exists ('needs agent.inbox.read' appears twice), but every sentence carries important operational information, making it dense though not bloated.

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 deprecation status, replacement tool, functional behavior, relevant parameters, required scopes, key type restrictions, and behavioral caveats. With an output schema present, the agent can determine return shape; the only minor omission is an explanation of the `limit` parameter, but this is less critical given the strong context otherwise.

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 schema description coverage at 0%, the description must explain parameters. It explains `item_id` as 'filters one item' and that it needs `agent.inbox.read`, but it never mentions `limit`, its default, maximum, or how it affects paging. So it adds partial value but leaves one parameter semantically undocumented.

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 'Deprecated: use get_inbound_activity' and then explicitly states the tool reads 'current authorized inbox retrieval receipts and agent-reported outcomes' via a specific endpoint. This clearly identifies the verb, resource, and even the alternative, distinguishing it from sibling tools like get_agent_inbox_context.

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 use get_inbound_activity instead, and states this endpoint is 'still served unchanged during the alias window,' providing a clear condition for when this tool should still be called. It also warns against substituting other keys or mail APIs after denial, which is actionable 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses significant behavioral traits: 'Records retrieval, not processing or facility completion,' 'No provider call or signed image URL,' 'OCR is untrusted; missing/pending/failed text is not success,' and 'Never substitute another key or mail API after denial.' These add substantial value and do not contradict 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 dense, unstructured wall of text. It front-loads the deprecation warning effectively, but then dumps multiple distinct caveats and requirements in a single run-on paragraph. There is no bullet formatting or logical grouping, making it hard to parse quickly. Several sentences are valuable, but the organization undermines readability.

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—deprecated, multiple caveats, authentication requirements—the description covers nearly everything: deprecation, alternatives, return behavior, scope requirements, and warnings. The only notable omission is explicit parameter semantics, but the output schema exists and covers return values. The sheer volume of caveats makes it complete, even if dense.

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 has 0% description coverage, and the description never explicitly defines the single required parameter item_id. It only hints at it via the URL path '/v1/agent-inbox/:id/context', but does not state that item_id is the inbox item identifier. For a one-parameter tool, this is a clear gap that the description should have closed.

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 tool as a versioned context/reporting reader for agent inbox items, explicitly distinguishing it from siblings like get_agent_inbox_sources (OCR) and get_agent_inbox_scan (capture drilldown). It also names the preferred replacement (get_inbound_item), so an agent immediately understands its role 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?

The deprecation warning 'use get_inbound_item' provides explicit when-not-to-use guidance. It also directs to get_agent_inbox_sources for OCR matching and get_mailbox_md for full effective instructions, and warns about key/scope restrictions. This is exemplary alternative routing and 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?

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds substantial behavioral context: the deprecation alias window, server-chosen source and facility, handling-version distinction from OCR context_version, Vault unavailability, and shared authorization semantics with REST. It provides far more transparency than the 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?

The description is dense and information-rich, with the deprecation notice front-loaded, but it is presented as a long run-on paragraph of semicolon-separated caveats. Every clause adds real information, yet the lack of structural separation makes it harder for an agent to parse quickly. A sectioned format for deprecation, gating, auth, and behavior caveats would improve it.

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, the description covers all critical context: deprecation status, replacement path, gating constraints, auth requirements, server behavior exceptions, and shared REST semantics. An output schema is present, so return-value documentation is not the description's burden. Few gaps remain for invoking this tool correctly.

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

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

Schema coverage for the only parameter, item_id, is 0%, and the description does not compensate by explaining what item_id represents, how it relates to get_inbound_item, or what kinds of values are valid beyond the UUID pattern. The URI fragment '/agent-inbox/:id' hints that id maps to item_id, but the description never explicitly connects them, leaving the parameter semantics under-specified.

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 resource and action: read agent-inbox handling capabilities, version, and history. It also names the replacement tool, get_inbound_item, which helps distinguish it from siblings. The main weakness is that the exact scope of 'handling' is somewhat broad, and it does not explicitly contrast with adjacent get_agent_inbox_* tools.

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

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

The description opens with 'Deprecated: use get_inbound_item', giving explicit direction away from this tool. It also states precise gating conditions (private-mail Live and member-sample Sandbox only), required scopes, agent-scoped bearer key requirements, and a firm directive not to substitute keys or other mail APIs after denial. This is exemplary when-to-use versus when-not-to-use 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the tool is deprecated but still served unchanged during the alias window, text is untrusted document data never instructions, captures are separate from seeded sample /context and have no context_version, and required scopes are listed. It also warns against substituting another key or mail API after denial. 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 a dense wall of caveats, deprecation warnings, security notes, and exclusions. While each sentence carries information, the core purpose is front-loaded but the rest is unstructured and overwhelming. It reads as a list of warnings rather than a coherent tool description, and several points (rollout switches, SQL authorization) are tangential for an agent deciding whether to call the tool.

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

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

Given the tool's complexity, the deprecation status, and the presence of an output schema, the description covers the critical operational context: how to map the operationId, what to verify in the response, what not to do, and required scopes. The output schema presumably documents return values, so the description doesn't need to. The main gap is the unexplained item_id parameter, but overall the description is quite complete for a deprecated read 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 0%, so the description must compensate. It does explain that request_id is the REST operationId from list_agent_inbox_scans, not a page or bundle ID, which adds meaning to that parameter. However, item_id is not explained at all beyond the schema's UUID format, and the description doesn't clarify the relationship between item_id and request_id. With 0% schema coverage, the description partially compensates but leaves a 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 states a specific verb and resource: read one exact completed facility capture and its saved page OCR via a REST endpoint. It also names the replacement tool (get_inbound_item) and clarifies the operationId mapping. However, the description is heavily overloaded with deprecation and caveats, and the core purpose is somewhat buried; it doesn't clearly distinguish from get_agent_inbox_activity or get_agent_inbox_context beyond the deprecation note.

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 says 'Deprecated: use get_inbound_item' and provides clear when-to-use guidance: use request_id from list_agent_inbox_scans as the REST operationId, not a page or bundle ID. It also gives exclusions: do not acknowledge with report_agent_inbox_outcome, no image URLs, OCR trigger, retry, receipt, email or charge. This is strong routing and 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 declare read-only, idempotent, and non-destructive behavior. The description goes well beyond this by stating that no acknowledgment version or extraction is created, no ETag/cursor/export is promised, no receipt or charge is generated, pagination is a current view rather than a snapshot, and scoped agent keys are required. 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 deprecation and purpose, but it is very long and packs in many security, retry, pagination, and exclusion caveats. While most sentences carry useful information, it is not concise and could benefit from tighter 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 output schema exists and the tool is complex, the description is remarkably complete. It covers deprecation, purpose, authentication, pagination behavior, performance guidance, retry semantics, exclusions, and points to outputSchema for field meanings and sort order. 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 0%, so the description must compensate. It explains limit/offset ranges and defaults, notes that sources use has_more with offset plus returned length, and refers to 'item_id pages.' It does not explicitly define item_id as the inbound-item identifier, but the context is sufficient for correct invocation.

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

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

The description opens with 'Deprecated: use get_inbound_item' and then states it is the 'Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources.' This gives a specific verb, resource, and endpoint, while explicitly pointing to the replacement sibling. The purpose is unambiguous and differentiated 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?

It explicitly says to use get_inbound_item instead, frames this tool as a legacy alias, and provides strong operational guidance: use after list_agent_inbox, narrow queries/date windows, fetch selected items, and avoid polling every mailbox. It also identifies exclusions like managed-PMB custody and forwarded email.

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 declare readOnlyHint=true, but the description states the call "Automatically marks facility messages as read," which is a state mutation in the environment. This directly conflicts with the read-only annotation, so the disclosed behavior contradicts the structured safety profile despite the description otherwise being informative.

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

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

Five short declarative sentences, each carrying distinct information (purpose, routing, ordering/roles, pagination, side effect), with the core purpose front-loaded. 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?

With an output schema present, return values need not be described, and the description covers ordering, sender roles, pagination, and the read-marking side effect. The main gap is the absence of any when-to-use routing among the many sibling read tools, and the annotation conflict noted above.

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 (limit, before), so the schema already carries the syntax. The description adds only a generic "Supports cursor-based pagination" note, while the more useful ordering detail (reverse chronological) is behavioral rather than parameter-specific, making this a baseline case.

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?

"Read the message thread with your mailbox facility" gives a specific verb (read) and resource (facility message thread), and the mention of sender roles further pins down the content. It does not, however, explicitly differentiate itself from close siblings like list_facility_conversations or get_postal_thread, so an agent must infer the boundary.

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 never states when to use this tool versus alternatives such as list_facility_conversations or get_postal_thread, nor any prerequisites or exclusions. "Facility routing is automatic" is contextual reassurance, not usage guidance, so usage must be inferred entirely from the name.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds that a row proves event recording, not OCR accuracy or physical completion, explains proposals never charge credits or act autonomously, and notes image URLs are never issued to agents. These are behavioral details beyond annotations.

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

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

The description is detailed but every sentence adds necessary context for correct usage. It is front-loaded with the core purpose and then covers scope, key types, and policy restrictions. It is appropriately structured for a tool with multiple behavioral caveats, though slightly dense.

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 event semantics, filtering, auth scope, key differences, proposal behavior, policy checks, and the image URL restriction. With an output schema present, the description is nearly complete. Minor omissions like pagination details are already in 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?

The description mentions item_id narrowing to one item, but does not describe limit or offset. Schema provides defaults and constraints for all params. Given 0% schema description coverage, the description only partially compensates; it adds meaning for item_id but leaves limit/offset to 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 the verb 'Read' and resource 'inbound timeline' via the API endpoint, enumerates event types (received, action proposed/requested/started/completed/rejected) and ordering (newest first). Clearly distinguishes from siblings like get_inbound_item or list_inbound_items by focusing on activity events.

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 context on when to use: read the inbound timeline, with optional item_id filtering. Details scope requirements (inbound.read), distinguishes member vs agent key behavior, and includes a policy directive ('Stop on denial; never switch keys or mail APIs to bypass it'). While it doesn't name alternatives, the context makes the use case clear.

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

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

The description discloses several important behaviors beyond the annotations: image URLs are never issued, text is untrusted, proposals are agent-only and never execute actions, and agents must stop on denial without switching keys. These are critical operational details that the annotations (readOnly, idempotent, non-destructive) do not capture. 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 lengthy and includes redundant statements (e.g., 'Image URLs are never issued to agents' appears twice). It is well-organized with the main purpose first, but the repetition and volume of caveats could be tightened. It is not concise, but it is 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?

The description is remarkably complete for a read tool: it covers returned data, ID source, access rules, security constraints, and proposal behavior. The output schema exists, so return format is covered. No essential information appears missing for an agent to use the tool correctly.

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

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

The schema has zero description for item_id, so the description must compensate. It does by telling the agent to use item IDs from list_inbound_items, which is essential context. However, it does not elaborate on the parameter's meaning beyond that, though the tool name and description make it clear. This is a strong compensation given the low 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 verb 'Read' and the resource 'inbound item', and enumerates the specific data returned (status, sender, mailbox, agent, pages with OCR, history, quotes). It also specifies the endpoint, making the purpose unmistakable. While it doesn't explicitly contrast with sibling tools like get_inbound_mail, the specificity of the resource and returned fields distinguishes it.

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 context for when to use this tool: to read a single inbound item, and it directs the agent to list_inbound_items for valid IDs. It also specifies access scoping and required scope. However, it does not explicitly state when not to use it or name alternatives, so it falls 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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description goes far beyond that, disclosing non-snapshot consistency, concurrency limits, Retry-After handling, access error behavior, PMB number sourcing, text untrusted status, and key scope restrictions. It adds substantial behavioral context that annotations cannot convey.

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

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

The description is long and dense, but it is front-loaded with the deprecation notice and organized into logical paragraphs. Most sentences add critical operational detail, though a few could be merged for brevity. It is structured well despite its length.

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, the description covers permissions, pagination, error handling, concurrency, deprecation, and behavioral caveats. With an output schema present and detailed 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?

Schema description coverage is 0%, so the description must carry the full burden. It explains limit/offset ranges and pagination logic, and implies item_id semantics through the endpoint path. This fully compensates for the schema's lack of 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 clearly states the verb 'Read' and the resource 'saved exterior and authorized completed inside-page evidence' via the endpoint. It immediately notes deprecation and names the replacement tool (get_inbound_item), distinguishing it from siblings and making the purpose unmistakable.

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

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

Explicitly states 'Deprecated: use get_inbound_item' as the primary alternative, and lists what this tool does not do (no extraction, retry, etc.), plus required permissions and when to use it. The guidance is unambiguous 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds valuable behavioral context: 'compact draft_context by default' and 'stable payload', which go beyond the annotations and help the agent understand what the response will feel like.

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 purpose, immediately followed by usage guidance. Every word earns its place, no fluff or repetition of schema 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?

With an output schema present, the description need not enumerate return values. It explains when to use the tool, what type of data to expect (sender context, contacts, deadlines, files, thread linkage), and the default behavior. This is complete for a single-item retrieval tool with robust 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 fully documented in the schema. The description adds minimal semantic value beyond the schema, only implying default behavior ('compact draft_context by default') which aligns with the include parameter's documented default. Baseline 3 is appropriate when schema carries the explanatory weight.

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 and resource: 'Get one forwarded inbound mail item with compact draft_context by default.' It distinguishes from siblings like get_outbound_mail and list_inbound_mail by specifying this is for a single inbound item and for pre-reply drafting context.

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 'Use this before drafting an outbound reply when you need sender context, reply contact candidates, deadline clues, source files, and thread linkage in one stable payload.' This provides clear context for when to use, but doesn't explicitly name alternatives or exclusions like list_inbound_mail for multiple items.

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 safety profile is clear. The description adds the beta-access restriction and 'approved accounts' context, which is valuable behavioral information not present in the annotations. It does not explain what happens if beta access is missing, but this is a minor gap.

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 tool's purpose and access requirements, second provides an alternative. It is front-loaded, free of redundancy, and every sentence serves a distinct function.

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 zero parameters, a documented output schema, and clear annotations (read-only, idempotent), the description fully covers usage context. It also notes the beta access constraint and alternative tool, making it complete for practical decision-making.

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 description need not elaborate on parameter details. The baseline for 0 parameters is 4, and no additional parameter explanation is needed.

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 retrieves the agent's real mailing address (street address + mailbox number) for beta-approved accounts, and explicitly distinguishes it from the sibling list_inbound_forwarding_addresses tool by noting that tool returns a private intake alias for general inbound context.

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 tool only for the beta mailbox address, and for generally available inbound context, use list_inbound_forwarding_addresses instead. This directly addresses alternative 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the returned content (version, hash, timestamp) and advising caching and dependency for sync verification. This provides behavioral context beyond what annotations offer, though minor details like error conditions are omitted.

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 well-structured sentences: first states purpose, second details return fields, third gives critical usage guidance. No wasted words; information is front-loaded and dense.

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 zero parameters and presence of an output schema, the description covers all necessary context: what the tool does, what it returns, and how to use its output (caching and passing the version to send_outbound_mail). It fully equips the agent to use the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so the baseline is 3. The description does not need to explain parameters; it instead focuses on return values and usage, which 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 retrieves the renter's MAILBOX.md standing instructions, specifies the exact return fields (full instruction text, version number, content hash, last update timestamp), and implicitly distinguishes it from siblings like get_mailbox and propose_mailbox_md_edit by highlighting its specific role in sync verification for send_outbound_mail.

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

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

Explicit guidance is given: 'Call this on startup and cache the version — you must pass it to send_outbound_mail for sync verification.' This tells the agent when to use it and how to use the result, but does not explicitly state when not to use it or mention alternatives, though the sibling list provides 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 mark the tool as read-only/idempotent. The description adds valuable behavioral context: legacy records may contain direct document URLs, while encrypted documents are fetched via a REST endpoint requiring document.read scope. This goes beyond the annotations and helps the agent anticipate authentication and data-format nuances.

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 main purpose, and the second adds an important caveat about document retrieval. No fluff; every phrase 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 the full scope of returned data (including metadata, failure info, photos) and describes the special case for encrypted vs. plaintext documents. Together with the output schema, it is fully complete for this get-by-id 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% (mail_id is described as UUID of the job to retrieve). The description adds no extra meaning about the parameter itself, so the baseline 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 clearly states the tool retrieves full details of a single outbound mail job, listing specific fields (recipient, mail class, cost, status, etc.). This distinguishes it from siblings like list_outbound_mail (which lists jobs) and get_inbound_mail (which handles inbound).

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: call this when you need comprehensive details for a specific outbound mail job (by ID). It does not explicitly name alternatives, but the context is clear enough that it is the detail endpoint vs. a list or action 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=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds minimal behavioral context beyond mentioning 'optional timeline events,' which is already present in the schema. It does not describe additional behaviors like empty results or error cases.

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, first stating the action and optional component, second giving the recommended use case. Every word earns its place without redundancy or fluff.

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 is simple (2 params, output schema provided), and the description plus annotations fully cover safety, purpose, and usage context. No significant gaps remain for the agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, with both parameters fully documented in the schema. The description's mention of 'optional timeline events' adds no new meaning beyond the 'include' parameter schema. The baseline of 3 applies when the schema carries the semantic weight.

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

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

The description clearly states the tool's function: 'Get one physical-mail thread with optional timeline events.' It specifies a distinct resource (a single postal thread) and action, distinguishing it from siblings like list_postal_threads. The additional use case sentence explains the tool's purpose in business terms.

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 clear usage context: 'Use this to explain how a generated outbound mail piece relates back to prior inbound scans and review decisions.' This implies when to use it, though it does not explicitly mention alternatives or when-not-to-use scenarios.

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, and non-destructive behavior. The description adds useful context about return content (billing events, costs, credits) and the default period. It also notes that 'only the signed-in human can add funds,' which provides auth-related context beyond annotations.

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

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

Three concise sentences front-load the main purpose, include key behavioral details, and provide a specific use-case. 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?

The description is complete given its complexity: output schema covers returns, annotations cover safety, and the description covers purpose, defaults, and a concrete usage scenario. Nothing significant 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 descriptions cover both parameters fully (100% coverage). The description adds value by summarizing the combined default behavior: 'Defaults to the current billing period if no dates are specified,' reinforcing optionality and providing a holistic view of the 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?

The description clearly states the tool's function: 'Get usage summary, billing events, and prepaid credit balance for a time period.' It specifies output content (itemized events, costs, totals, credits) and is distinct from sibling tools focused on mail, packages, and scans.

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 when to use: 'Use this in Cursor/MCP chat when the human asks how many mailbox.bot credits are left' and even prescribes how to respond. Also explains default behavior when no dates are provided.

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 read-only and idempotent behavior. The description adds critical context: returns metadata not text, no fuzzy search or new OCR, sandbox vs live data differences, pagination cap of 10000, and credential requirements. It also explains the rollout and scoping constraints, going well beyond the annotation 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?

Though long, the description is dense with necessary information and front-loads the deprecation warning. Every sentence adds value, covering purpose, usage, constraints, and alternatives without redundancy. The structure is logical and scannable.

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

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

With an output schema present, the description need not detail return fields. It covers all essential operational details: search behavior, pagination, scopes, environment differences, and credential constraints. Nothing critical is missing for an agent to use the tool correctly.

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

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

Schema coverage is 0%, but the description thoroughly explains q as a literal AND search with length/term limits and required scope, and explains received_after/received_before semantics (inclusive/exclusive, filtering stored timestamp, rollout requirements). It also references offset/limit via pagination guidance. This fully compensates for the lack of 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?

The description clearly states the tool lists/searches assigned postal mail, names the replacement tool (list_inbound_items), and distinguishes itself from siblings. It even notes the service endpoint. This leaves no ambiguity about what the 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?

It explicitly declares the tool deprecated and directs users to list_inbound_items. It also provides detailed conditions for optional parameters, pagination limits, and scope requirements, effectively guiding when and how to use it versus 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?

Annotations already declare read-only and idempotent, and the description adds substantial behavioral detail: pagination cap at offset 10000, OCR status values, that completion is not extraction success, and that no provider/retry/ack/receipt is triggered. It also notes the deprecation and the alias window, which are not in 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 dense and long, but every sentence carries critical operational information (deprecation, pagination, scopes, OCR semantics). It is front-loaded with the deprecation notice, though the single paragraph could be better structured with lists or separation.

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 (deprecation, sandbox restrictions, pagination, OCR states, scope requirements, rollout notes) and that an output schema exists, the description covers all necessary calling context. It leaves little for an agent to infer incorrectly.

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 0%, so the description must explain parameters. It thoroughly explains q (literal AND, NFKC/lowercase normalization, 200-char/12-term limits) and pagination via offset/limit. However, item_id is only implied through the path ':id' and is not explicitly mapped, leaving a small 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 explicitly states the tool lists and searches completed facility-captured scan jobs, and immediately flags it as deprecated in favor of get_inbound_item. It names the verb (list/search) and resource (scan jobs) and distinguishes itself from the replacement sibling.

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 opens with 'Deprecated: use get_inbound_item,' which is an explicit instruction to prefer an alternative. It also clarifies sandbox-only usage, required scopes, and key restrictions, giving clear when-to-use and when-not-to-use 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds almost no behavioral context beyond that—no mention of pagination behavior (beyond the schema), sorting, or what 'conversation' contains. Since an output schema exists, return details are less critical, but the description still contributes little.

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

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

Two sentences, front-loaded with the action, and no filler. The second sentence about automatic routing is somewhat cryptic but short. Efficient overall.

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 list tool with 2 optional params, full schema coverage, annotations, and an output schema, the description covers the basics. However, the ambiguous phrase 'mailbox facility' and lack of sibling differentiation leave gaps in an environment with many similar-sounding list/get tools.

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 two parameters (limit, offset) are already fully documented in the schema. The description adds no parameter meaning at all. Baseline 3 applies when the schema does the heavy lifting with high 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 states a verb (list) and resource (facility conversations), but 'your mailbox facility' is jargon that doesn't clearly map to a concrete resource, and it doesn't distinguish this tool from siblings like get_facility_messages or list_postal_threads. The purpose is vaguely inferable but not precise enough for confident selection.

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 is given on when to use this tool versus alternatives. With siblings such as get_facility_messages and list_postal_threads, an agent has no signal about which to pick. The note 'Facility routing is automatic' does not address when-to-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 mark the tool as readOnly, idempotent, and non-destructive. The description adds meaningful context: member-scoped aliases, live/sandbox key convergence, and the fact that the tool doesn't initiate OCR/uploads itself. This goes beyond the structured annotations.

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

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

Three sentences, with the core action in the first sentence and supplementary context in the following two. Each sentence earns its place: the second clarifies the relationship to OCR, the third explains member-scoping. No redundancy or unnecessary detail.

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 no parameters and has an output schema (so return values are covered elsewhere), the description fully explains purpose, the role of the aliases, and notable behaviors. It is complete for a simple discovery tool.

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

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

The tool has zero parameters, and schema coverage is 100% (vacuously). Per the baseline for 0 params, the description doesn't need to elaborate on parameters. It still adds useful context about what the aliases are for, which helps interpretation.

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 private inbound forwarding aliases, using specific verb 'List' and resource 'renter’s private inbound forwarding aliases'. It further distinguishes this from uploading files into OCR and from siblings like list_inbound_mail by clarifying it's a discovery-only tool.

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 explains the context of use: forwarding attachments initiates OCR, and this tool discovers the intake address without uploading directly. This implies when to use it (before forwarding) and when not (not for direct OCR upload), but doesn't explicitly name alternative tools for those actions.

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 read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: 'Saved-data reads only', 'Results are not snapshot-consistent', 'Bound concurrency, honor Retry-After... back off on transient failures', and scope restrictions. It also clarifies that these readers do not enable exterior automation or inside-page extraction beyond already-authorized data. 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 long but logically organized: search semantics → filters → return type → exclusions → pagination → consistency → rate limits → auth requirements. It is front-loaded with the core purpose and every sentence carries information not already present in the schema or annotations. For a tool with 7 parameters and many behavioral constraints, the length is justified.

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 the tool's complexity (search semantics, date filtering, pagination limits, scopes, concurrency, error handling), the description covers every invocation-relevant aspect. It even addresses edge cases like empty-search scope requirements and the prohibition on switching keys or accounts. 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 only 43%, but the description compensates thoroughly. It explains q's literal AND behavior, NFKC/lowercase normalization, 200-character/12-term limits, and cross-page matching. It clarifies received_after/before as inclusive/exclusive intake-time filters, and provides pagination guidance for limit/offset: 'follow pagination.has_more using offset plus returned count'. This prevents ambiguity for undocumented 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?

The description opens with a specific verb-resource pair: 'Search managed-renter physical mail through GET /v1/inbound-items?search_mode=documents.' It also clarifies what it returns ('item metadata and canonical owner/mailbox identity, not page text') and explicitly directs to a sibling for page sources, which distinguishes it from related tools.

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

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

The description explicitly names an alternative ('Use get_inbound_item_sources for selected items') and lists many non-goals ('no extraction, retry, signed image URL, facility action, provider call, email or charge'). It also provides prerequisites (saved-document reads, active managed mailbox, required scopes) and detailed pagination/error-handling guidance, giving an agent clear when-to-use and 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds non-redundant behavioral context by revealing that the default output includes a compact draft_context with specific elements (OCR context, reply contact candidates, deadlines, thread linkage), which helps an agent understand what the tool returns beyond the schema.

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 concise sentences: the first states the core function, the second explains the default output's purpose. Every word earns its place with no fluff or repetition.

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 a rich output schema and comprehensive annotations, the description is complete enough for an agent to know what the tool does, when to use it, and what to expect in the default output. It doesn't need to explain return values or pagination, as those are covered by the output schema and input schema. A minor gap is not explicitly contrasting with related list tools.

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 mentions 'Default output includes compact draft_context,' which aligns with the include parameter's default, but it does not add substantial meaning to any individual parameter 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?

The description uses a specific verb ('List') and identifies the resource ('inbound mail items') with a precise qualifier ('forwarded ... captured from private forwarding aliases'), clearly differentiating it from sibling tools like list_outbound_mail and get_inbound_mail.

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

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

The description explicitly states a use case: 'so an LLM or external agent can reason about OCR context, reply contact candidates, deadlines, and thread linkage before generating outbound mail.' This gives clear context for when to use the tool, though it doesn't explicitly name alternatives or exclusion 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context by enumerating the returned fields (mail ID, recipient, mail class, status, cost, timestamps, failure metadata) and the filtering capabilities. This goes beyond the annotations and helps the agent understand what to expect from the response, especially the failure metadata which could be critical.

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, front-loading the core purpose and immediately listing return fields and filters. There is zero filler or redundant information. Every sentence provides distinct information, making it efficient and easy to parse.

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

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

Given that an output schema exists, the return format is documented separately. Annotations cover the read-only/idempotent/destructive safety profile. The description covers the purpose, return fields, and filtering dimensions, which are the key operational aspects. Nothing an agent needs to call this tool 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 7 parameters are thoroughly documented in the schema itself. The description summarizes the filters (status, date range, search) but does not add new semantics beyond what the schema already provides. The baseline of 3 applies since the schema does the heavy lifting, and the description adds marginal value by grouping related filters.

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 'List outbound mail jobs with status tracking.' This clearly states the verb (list), resource (outbound mail jobs), and purpose (status tracking). It distinguishes itself from sibling tools like get_outbound_mail (which implies single retrieval) and send_outbound_mail (creation). The specificity is high 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 explains what the tool does and its filtering options, but it doesn't explicitly state when to use this tool versus alternatives like get_outbound_mail or list_inbound_mail. The usage context is implied but not contrasted with siblings. It provides no exclusions or explicit guidance on selecting this tool over others.

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 the tool as read-only, idempotent, and non-destructive, so the description needn't repeat those. The description adds context about the thread grouping semantics, explaining that threads tie together inbound mail and outbound documents. It doesn't disclose specific behavior like pagination or default sorting, but those are covered by the schema and output schema.

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 action verb and resource, and both sentences contribute: one defines what the tool does, the other explains its purpose. There is no redundant or unnecessary wording.

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, 5 optional documented parameters, and an output schema, the description sufficiently covers the tool's purpose and use case. It lacks explicit alternatives/exclusions but those are not essential for a list operation with good schema support.

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?

All five parameters have descriptions in the schema (100% coverage), so the description doesn't need to elaborate on them. The description doesn't add parameter-specific meaning beyond the schema, but the baseline is 3 given the 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 clearly states the tool lists physical-mail threads and explains their function of grouping inbound context, human review, and outbound sends. This distinguishes it from sibling list tools like list_inbound_mail and list_outbound_mail, which focus on individual items rather than workflow grouping.

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 an explicit use case: 'Use this to understand which inbound items and outbound documents belong to the same business workflow.' This gives clear context for when to choose this tool over alternatives, though it doesn't explicitly state when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds substantial non-obvious context beyond that: 2xx means receipt rather than external processing, signing secrets and receiver response body are omitted, and the exact payload fields are disclosed. This is rich behavioral disclosure, not a restatement of 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 uses compact, information-dense sentences for caveats, permissions, and semantics. It is longer than the minimum, but each clause carries useful operational information; only the idempotency_key guidance feels slightly tangential to a read-only call.

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 single-parameter, read-only tool with an output schema available, the description covers scope, payload contents, response interpretation, exclusions, authorization, environment, and documentation. An agent has enough information to invoke it correctly and to interpret results without further lookup.

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 0%, but the description compensates by clarifying that the operation is 'for one webhook' and by tying authorization to /api/v1/webhooks/endpoints, making endpoint_id's role reasonably clear. It does not explicitly describe the parameter by name, and the idempotency_key mention is not part of the request schema, leaving minor ambiguity; still, with one self-named parameter this is adequate.

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 ('Read') and resource ('latest 50 deliveries and their exact JSON payloads') with clear scoping to 'one webhook'. The phrase 'never page text' further distinguishes the payload content from other inbox/mail tools. This is unambiguous even among siblings like list_webhook_endpoints and replay_webhook_delivery.

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 context for when to use the tool, including the constraint to one webhook, the 'uncertain mutation' verification scenario, and the requirement for webhook.manage. It does not explicitly name alternatives or state when not to use this tool, 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 cover readOnly, idempotent, non-destructive, and closed-world behavior; the description goes beyond them by disclosing the required permission (webhook.manage), the authorization scope (tenant/agent/Live-Sandbox), and that secrets are not returned. It also clarifies that legacy agent callback settings are out of scope, adding meaningful behavioral context without contradicting annotations.

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

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

The main action is front-loaded and the description is reasonably compact, but not every sentence earns its place: 'Reuse the exact idempotency_key and input after an uncertain mutation' seems copied from mutation tools and is confusing for a read-only, zero-input list endpoint. The permission and auth sentences are dense but relevant, keeping the description somewhat efficient overall.

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 a rich output schema and annotations, the description is nearly complete: it covers scope, permission, authorization boundaries, exclusions, and provides a documentation link. The irrelevant idempotency note is a minor clarity issue but does not leave an agent without the information needed to call 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 tool has zero parameters and the input schema is complete, so there is nothing for the description to add about individual parameters; the baseline-4 rule applies. The description does add value by specifying what the returned webhook data includes and excludes, which helps an agent interpret the output.

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—'List the member's webhooks'—and enumerates the returned fields (name, URL, events, keyword rules, status) while excluding secrets. It also notes that legacy agent callback settings are separate, but it does not explicitly name sibling tools like list_webhook_deliveries or create/update endpoints, so the sibling differentiation is partial.

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 an implicit exclusion for legacy agent callback settings and mentions the required permission and authorization model, which is useful. However, it does not explicitly say when to prefer this tool over sibling webhook tools (e.g., list_webhook_deliveries for delivery history), and the idempotency instruction appears aimed at mutations rather than this zero-parameter read.

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 (idempotentHint=true), the description details idempotency_key reuse, required scopes, agent-scoped bearer key, and explicit limitations (cannot self-approve, dispatch postage, charge, destroy, or complete work). It also clarifies that the open_and_scan sample is test training, not paid OCR, providing real behavioral context that annotations do not cover.

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

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

The description is a single dense paragraph without bullet points or section breaks, making it harder to scan. However, every sentence carries necessary information given the tool's complexity and deprecation status, so it is not verbose. A more structured layout would improve readability, but the content is appropriately sized.

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 (three action types, nested request object, auth requirements) and the presence of an output schema, the description covers all essential context: deprecation and alternative, prerequisites (read capabilities first), per-action constraints, idempotency guidance, authentication scopes, and limitations. 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?

With 0% schema description coverage, the description compensates by explaining key parameter constraints: confirmed and destructive_confirmed should be false, forward requires a complete US destination and mail class, discard needs subsequent confirmation, and idempotency_key must be reused with identical body and expected_version. While not exhaustively covering every field, it adds significant meaning beyond the raw schema.

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

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

The description clearly states the tool's purpose: proposing handling actions (open_and_scan, forward_original, discard_original) for agent inbox items via a specific endpoint. It explicitly distinguishes itself from the replacement tool request_inbound_action, and lists what it cannot do, leaving no ambiguity about its scope.

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

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

The description begins with the explicit deprecation and points to request_inbound_action as the preferred alternative. It provides concrete usage conditions: require confirmed:false and destructive_confirmed:false, read capabilities/version first, forward needs US destination and mail class, discard needs subsequent confirmation, and never substitute another key or mail API after denial. This is comprehensive guidance for when and how to use the 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?

The description adds valuable behavioral context beyond annotations: the renter sees the suggestion in their dashboard and can accept, reject, or modify it. This clarifies that the tool does not directly apply changes but proposes them, which is not disclosed by the annotations (readOnlyHint=false, destructiveHint=false).

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 consists of two concise sentences: the first states the purpose and workflow, the second gives usage context. Every sentence earns its place with no unnecessary wordage.

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, the schema covers parameters, the output schema covers return values, and the annotations cover safety profile. The description effectively explains the purpose, the proposal workflow, and when to use, making it complete 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 both parameters clearly described (reason and suggested_content). The description itself does not elaborate on parameters, but the schema already provides sufficient semantics, so a baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Propose changes to the renter's MAILBOX.md instructions' with a specific verb and resource. It also distinguishes from siblings by emphasizing the proposal nature (renter can accept/reject/modify), unlike direct write or rule-creation tools.

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

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

The description provides explicit guidance: 'Use this when you observe patterns that could be codified into standing instructions.' This is clear context for when to use, though it does not explicitly mention alternatives or when not to 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?

Beyond annotations, it discloses key behaviors: preserving event_id for deduplication, rechecking the current endpoint revision, requiring webhook.manage, and sharing a specific authorization model. It also clarifies negative behaviors, such as not replaying successful deliveries or approving facility handling.

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 core purpose and keeps every sentence purposeful, covering preconditions, exclusions, permissions, and idempotency guidance. It is slightly longer than strictly necessary, particularly the control-plane authorization sentence, but it avoids 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 four required parameters, an output schema, and annotations, the description is largely complete: it covers when to use it, what it does not do, permission requirements, and idempotency behavior. Minor ambiguity remains about failure semantics if the expected_revision does not match, but this does not block 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 0%, so the description must compensate. It indirectly explains expected_revision via 'rechecks the current endpoint revision' and idempotency_key via 'Reuse the exact idempotency_key and input after an uncertain mutation.' However, delivery_id and endpoint_id rely mostly on their self-explanatory names rather than explicit 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 uses a specific verb and resource: 'Explicitly retry a failed delivery after correcting the receiver.' It clearly distinguishes this from sibling tools like list_webhook_deliveries and test_webhook_endpoint by stating the exact action and its precondition.

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 and explicit exclusions: retry only after correcting the receiver, do not replay successful deliveries, and do not approve facility handling. It also states the required permission and the idempotency-key reuse guidance, though it does not name a specific alternative 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 only indicate readOnly=false and idempotent=true; the description adds far more: deprecation status, idempotent retry semantics, required scopes, agent-scoped bearer key restrictions, and the limitation that reports do not approve or complete facility handling. This is substantial behavioral context beyond what structured fields provide, and it does not contradict the annotations.

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

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

The description is a dense wall of text with redundancy: the required scopes are stated twice. The sentence about rollout switches, member approval, assignment, credential environment, and SQL authorization is opaque and does little to help an agent invoke the tool. The deprecation notice is well front-loaded, but overall structure and brevity are weak.

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, the description covers deprecation, authentication scopes, idempotency retry behavior, and important limitations. The output schema presumably covers return values, so the absence of response details is acceptable. The main gaps are clarifying item_id semantics and trimming confusing cross-references to REST authorization details, but the definition is still largely sufficient.

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 0% schema description coverage, the description compensates by explaining that context_version must be the exact fetched value, run_id must be non-sensitive, and retries must reuse the same idempotency_key and request. It does not explicitly define item_id, though the endpoint path's :id hints at its role, so the parameter semantics are mostly but not fully clarified.

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 a specific verb and resource: report actual external-worker processing through /v1/agent-inbox/:id/acknowledgments. It also draws a boundary by saying reports cannot approve or complete facility handling, which helps distinguish it from related inbox actions. The deprecated/no-successor note is upfront and adds clarity rather than obscuring 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?

Gives concrete use instructions: send exact fetched context_version, outcome, and non-sensitive run_id, and retry only with the same idempotency_key and request. It also provides exclusions: never report work before doing it and reports cannot approve or complete facility handling. No alternative tool is named, but that is expected since the description explicitly states there is no successor.

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

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

Goes well beyond the annotations by disclosing that proposals never charge credits, buy postage, move mail, or execute the action themselves; also reveals server-side policy checks, the one-open-action constraint, required scope, and denial behavior. This prevents dangerous assumptions about immediate execution.

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 purpose, but the description repeats the proposal-waits-and-never-acts point twice and restates the inbound_policy check twice. Sentences like 'Image URLs are never issued to agents' add tangential detail and bloat the text beyond what is needed.

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 required scope, idempotency behavior, version conflicts, destination constraints, policy enforcement, concurrency limits, and denial handling. With an output schema present, it does not need to describe return values, and the description supplies enough operational detail 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?

Compensates for 0% schema coverage by explaining expected_version as the item's current version, idempotency_key as a stable retry key, and the US destination requirement including untracked_acknowledged for first_class. Optional fields like expected_quote and mail_class are not explained, but the core required parameters receive meaningful operational guidance.

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?

Specifies a clear verb ('Propose'), the exact resource ('/v1/inbound-items/:id/actions'), and enumerates the three action types (scan, forward, discard). This unambiguously identifies what the tool does and distinguishes it from generic sibling operations.

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

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

Provides strong context: agent keys only, owner approval always required, policy checks on forward/discard, and a hard rule to stop on denial. It does not explicitly name alternative tools or when to prefer them, but the usage boundaries are clear.

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

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

Beyond the annotations, it discloses the 24-hour overlap window for old signatures, the need to update receiver secret configuration, the requirement to never leak secrets in logs or prompts, and the webhook.manage permission. This turns the destructiveHint into actionable behavioral context without contradicting the annotations.

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

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

The description is dense and front-loaded with the core action and its precondition. Every sentence adds operational or safety value, though authorization is mentioned twice ('Requires webhook.manage' and 'same ... authorization'), a minor redundancy in an otherwise tight 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?

For a destructive webhook secret rotation, the description covers authorization, side effects, security constraints, idempotency, and includes a docs link; the output schema removes the need to document return values. It is slightly incomplete only because expected_revision's concurrency/optimistic-locking role is left to inference.

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 0%, so the description must carry the parameter-semantics burden. It explains confirm_rotation as the explicit consent gate and gives meaning to idempotency_key through the retry instruction. However, endpoint_id and expected_revision are left undocumented beyond their names, so compensation is only partial.

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: 'Rotate the signing secret'. This clearly distinguishes the tool from sibling webhook tools like update_webhook_endpoint or test_webhook_endpoint, whose purposes are different. It also makes the safety-gated nature of the operation 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 gives strong usage conditions: rotate 'only with explicit operator authorization and confirm_rotation:true', and reuse the exact idempotency_key after an uncertain mutation. It does not explicitly name alternatives or state when not to use the tool, so it falls just short of full when/when-not 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 add idempotentHint=true, but the description explains exactly what that means operationally ('Exact retry key/scenario reuses the fixture'). It also discloses the deprecation state, the auth model, shared rollout switches, SQL authorization sharing with REST, and the fact that fixtures deliberately exclude real mail, charges, facility tasks, PMBs, model calls, and member samples. None of it contradicts the annotations.

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

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

The prose is dense and ordered effectively: deprecation status first, then purpose, key constraints, exclusion scope, auth, shared-state caveats. It is slightly long and contains some overlapping security statements, so it is not maximally concise, but every sentence contributes operational 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?

With an output schema present and annotations already carrying idempotency and non-destructive hints, the description fills the important gaps: deprecation lifecycle, exact endpoint, auth prerequisites, behavioral boundaries, retry semantics, and shared execution environment. Nothing an agent needs to invoke it correctly appears to be 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 input schema has 0% description coverage, but the description compensates for the scenario parameter by naming the two allowed fixture types and for the idempotency key by describing retry-key reuse semantics. It does not repeat the schema's required/pattern constraints or formally label the idempotency_key, but enough meaning is added to make the parameters actionable.

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 action ('Explicitly seed an isolated provider-free two_page_letter or needs_review fixture') with the exact endpoint (/v1/agent-inbox/sandbox/seed) and scenario values. It also narrows the operation by saying what it is not (no member sample, real mail, model call, etc.) and by restricting to sandbox agent keys, which separates it from the many read-only agent-inbox and mail-related 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?

It gives explicit usage context: this is a deprecation-only fixture seeding endpoint, used to test reads/reports rather than handling. It provides hard when-not guidance ('Never substitute another key or mail API after denial') and makes key/scenario eligibility explicit, including the required agent.inbox.read scope and the prohibition on member/facility keys.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false). The description adds genuinely useful behavior beyond that: the message lands in a shared conversation visible to the renter and facility, routing is automatic, and links are optional context. It doesn't disclose rate limits or delivery semantics, but the audience/visibility disclosure is the key thing an agent couldn't infer.

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

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

Three tight sentences, front-loaded with the action and recipient, then routing behavior, then the optional context. No filler, though the linking sentence slightly overlaps the schema.

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

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

An output schema exists, so return values need not be explained. The description supplies the audience/visibility and routing behavior needed to call this correctly; only explicit alternative-tool routing and delivery expectations are absent, which is a minor gap for a straightforward send 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 all three parameters (body length range, package_id, action_request_id) are already documented. The description only restates the optional linking behavior, adding no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Send a message to the operator at your mailbox facility'), which is clearly distinct from physical-mail siblings like send_outbound_mail. It does not explicitly name a sibling to contrast against, but the recipient-scoped framing (facility operator) is 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?

It implies usage ('facility routing is automatic', optional package/action links) but never states when to use this versus send_outbound_mail or when to prefer get_facility_messages for reading. Context is suggested rather than spelled out; no exclusions or prerequisites.

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 fully discloses side effects: production keys spend prepaid mailbox credits, sandbox keys skip debits and fulfillment, dry_run avoids record creation, requires_approval defers the credit debit, and an optional Auto-Fill reload may be triggered. It also explicitly states agents never access Stripe, card data, or Auto-Fill settings, which aligns with and extends the annotations.

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

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

The description is highly detailed and front-loaded with the main purpose, but it is verbose and repeats pricing/color-cost information that also appears in the input schema. Some sentences could be condensed without losing meaning, so it is adequate but not tightly 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?

Given the tool's complexity—30 parameters, live credit spending, multiple mail classes, approval flows, and human-review requirements—the description covers all necessary operational context: credits, sandbox behavior, tracking requirements, cost caps, inbound attachment, and REST-only business runs. Nothing critical is missing for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond the schema by explaining cost_breakdown semantics, color surcharge vs total color price, mail class pricing floors, service_adjustment_cents, and the difference between dry_run and requires_approval. This gives agents a deeper understanding of parameter effects than the raw schema alone.

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

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

The description clearly states the tool's primary purpose: 'Submit a document for printing and postal mailing by the facility.' It also distinguishes live funded sends from sandbox/test behavior and dry-run previews, and provides enough detail to avoid confusion with sibling test mail tools.

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

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

The description gives explicit usage guidance: use dry_run=true to preview credits, requires_approval=true to defer debit, sandbox keys to skip fulfillment, and max_cost_cents to cap costs. It also instructs agents to show the human_review response before live funded sends, making when and how to use the tool unambiguous.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that the tool queues a delivery rather than performing HTTP delivery, requires webhook.manage permission, uses the same bounded control plane and tenant/agent/Live-Sandbox authorization as /api/v1/webhooks/endpoints, and advises reusing idempotency_key after uncertain mutations. This is meaningful behavioral disclosure that helps the agent understand side effects and retry semantics. It doesn't contradict 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 compact and information-dense: four sentences covering purpose, key distinction, auth, and idempotency guidance. It front-loads the core purpose and immediately clarifies the queue-vs-delivery distinction. Every sentence earns its place; no filler or repetition.

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, auth requirements, control plane context, idempotency retry guidance, and points to the relevant sibling for delivery inspection. It also links to webhook docs. The output schema exists, so return values need not be described. The only minor gap is that it doesn't explicitly define expected_revision semantics, but the schema's integer type and the 'bounded control plane' context make it reasonably inferable. Overall, quite complete for a tool with this complexity.

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 0%, so the description carries the burden of explaining parameters. However, the description does not explicitly explain endpoint_id, idempotency_key, or expected_revision beyond what the schema provides (types, formats, patterns). The idempotency guidance ('Reuse the exact idempotency_key and input after an uncertain mutation') adds some semantic meaning to idempotency_key, and 'expected_revision' is implied by the bounded control plane context but not explicitly defined. With 0% coverage, the description should compensate more, but the schema itself is fairly self-explanatory (uuid, integer, required). A baseline 3 is appropriate given the schema's clarity and the slight idempotency_key context added.

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

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

The description clearly states the tool's purpose: queue a synthetic webhook.test delivery (no item) to check the receiver and its signature verification. It distinguishes itself from related tools by explicitly noting that queue admission is not HTTP delivery and pointing to list_webhook_deliveries for inspection. The verb 'queue' and resource 'synthetic webhook.test delivery' 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 provides explicit usage context: it is for checking the receiver and signature verification, and it clarifies that queue admission is not HTTP delivery, directing the agent to list_webhook_deliveries for actual delivery inspection. It also mentions the sibling test_webhook_endpoint_with_sample implicitly by specifying 'no item' (synthetic webhook.test), which helps distinguish when to use this tool vs. the sample-based variant. The idempotency guidance ('Reuse the exact idempotency_key and input after an uncertain mutation') is a clear when-to-use instruction.

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

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

Beyond the annotations, the description discloses important behavioral traits: required webhook.manage permission, bounded authorization scope, no real-world side effects, the test's free/fictional nature, and the precise meaning of success. It also advises reusing the exact idempotency_key after an uncertain mutation, which aligns with the idempotentHint annotation and adds practical operational 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 yet information-dense, front-loading the core operation in the first sentence and then layering constraints, permissions, limitations, and a documentation link without redundancy. Every sentence adds operational 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 test tool with an output schema and annotations, the description covers the key contextual aspects: what the sample test does, side effects it avoids, required permissions, authorization scope, idempotency behavior, and proof semantics. It is slightly incomplete only because expected_revision is not given any meaning, and the exact conditions for 'if needed' are left vague.

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 0%, so the description carries the full burden for explaining the three parameters. It gives some guidance for idempotency_key ('reuse the exact idempotency_key and input after an uncertain mutation') and implicitly associates endpoint_id with 'this webhook', but expected_revision is never explained at all. This is a meaningful 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 identifies the action ('Run the Sample test'), the resource (a webhook endpoint), and the specific behaviors that distinguish this tool from siblings: it opens/scans a fictional Mojave sample letter, delivers real inbound.pages_ready / inbound.keywords_matched events, and computes a verdict from the receiver's HTTP result. It also explicitly states what success does and does not prove, making the tool's role unambiguous even next to test_webhook_endpoint.

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: it is for verifying transport receipt and optional keyword matching, not agent processing, and it emphasizes there is no mail/charge/email/facility side effect. It does not explicitly name sibling alternatives or give a direct 'use this instead of X' rule, but the behavioral boundary is clear enough for an agent to choose correctly.

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 indicate idempotentHint=true and destructiveHint=false, and the description adds important behavioral context: HTTPS requirement, 10-second response window, pausing delivery via enabled field, and enumerating all event types. 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, followed by necessary details about events and endpoint requirements. It is mostly concise, though the list of event types could potentially be shortened by referring to 'mail lifecycle events' while still being clear.

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, the description need not explain return values. It adequately covers the tool's configuration purpose, event subscription semantics, and endpoint constraints. However, it could mention idempotency behavior or whether updating one field resets others, though annotations partially cover idempotency.

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

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

Schema description coverage is 100%, and the description adds value by explaining the endpoint response requirements (HTTPS, 2xx, 10-second timeout) and event type semantics (mail lifecycle and inbound custody events), which are not in the schema descriptions.

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

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

The description starts with a specific verb ('Configure') and resource ('webhook endpoint URL and event subscriptions') and clearly distinguishes from sibling tools (none of which mention webhooks or real-time notifications).

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 use for webhook configuration but does not explicitly state when to use this tool versus alternatives or when not to use it. It lacks guidance on prerequisites or disambiguation from sibling tools like get_mailbox or list_outbound_mail, which handle different concerns.

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 already declare destructiveHint=true and idempotentHint=true, the description adds material behavior: 'Do not redirect notifications without the operator's authorization', 'Agent/environment scope cannot be changed', and the idempotency retry instruction. These go beyond the annotations and help an agent avoid unauthorized or dangerous 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?

Four dense sentences, each carrying a distinct fact: the update verb, the authorization caveat, the scope limitation plus auth model, and the idempotency instruction plus a docs link. No filler words and the primary action 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?

The description covers the action, permission requirement, scope limits, idempotent retry behavior, and points to documentation. With an output schema present and a detailed input schema, this is enough for a competent agent, though openWorldHint=true leaves room for additional undisclosed side effects that the description does not enumerate.

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 description maps top-level parameters to business concepts ('URL, events, keyword rules', 'active/paused status'), but with 0% schema coverage it does not explain the nested rules structure (match, source, terms, exclude_terms) or precisely how expected_revision governs the update. It partially compensates for the absence of schema descriptions but leaves several parameters under-explained.

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 — 'Update name, URL, events, keyword rules or active/paused status with expected_revision' — and enumerates the mutable fields. It clearly identifies this as a mutation of an existing endpoint, distinguishing it from create/test tools, though it does not explicitly contrast with the sibling update_webhook.

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 concrete operational guidance: 'Requires webhook.manage', 'Uses the same bounded control plane and tenant/agent/Live-Sandbox authorization', and warns against redirecting notifications without operator authorization. It also gives retry guidance — 'Reuse the exact idempotency_key and input after an uncertain mutation' — though it stops short of explicitly naming alternatives when to use them.

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