mailbox.bot

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

Adds substantial context beyond the annotations: completion marks every piece mailed and fires batch.completed, and the QR path fires batch.piece.* webhooks. That side-effect disclosure is valuable for a non-readOnly, non-destructive, non-idempotent tool. It stops short of saying what a repeat call does at the terminal 'completed' state, so idempotency behavior is left implicit.

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-loads the most decision-relevant fact ('Sandbox keys only') and covers both modes in three sentences with no filler. The middle sentence is densely packed, requiring a second read to separate the two modes, which keeps it out of top marks.

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 3-parameter mutation tool with an output schema and full annotations, the description covers scope restriction, state transitions, webhook side effects, and the alternate QR mode. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: qr_event and piece act together as an alternative mode rather than modifiers on the advance behavior. It doesn't add format or validation details beyond the enum and 1-based note already in the schema.

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

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

States a specific verb and resource ('simulate the facility one step' on a test batch) and spells out the state machine submitted → in_progress → completed. It also clearly delineates a second mode (qr_event + piece records a scan/confirm rather than advancing), so an agent can tell 'advance' from 'record a QR event' without opening the schema.

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

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

Gives an explicit precondition ('Sandbox keys only') and an explicit exclusion ('Live batches are advanced by the facility, never by the API'), which is exactly the when-not guidance an agent needs. It also states the condition that selects the alternate mode ('With qr_event and piece...instead').

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

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

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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavior: credits are refunded in full and the cancellation window is bounded by batch state. This is real value beyond the annotations, though it omits any auth or rate-limit context.

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

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

Two tightly written sentences with zero filler; the eligible states are front-loaded before the exception, which is the order an agent needs to evaluate feasibility.

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?

Return values need not be explained since an output schema exists, and the state preconditions plus refund consequence cover the agent's decision inputs. Minor gap: no mention of what happens for already-cancelled or invalid batches.

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

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

Schema coverage is 100% and the batch_id property already documents its UUID format and origin (create_batch_mail/list_batch_mail). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (cancel) and resource (batch mail) directly. The state gating (draft/paid/generating/submitted vs in_progress) makes the scope unambiguous and distinguishes it from sibling cancel_outbound_mail at a conceptual level.

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 lists the states in which cancellation is allowed and the one state (in_progress) where it is not, giving clear when-to-use and when-not-to guidance. It stops short of naming the alternative sibling tools, so it falls under a full 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?

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?

Adds substantial context beyond annotations: debit happens exactly once with idempotent repeat behavior (reinforcing idempotentHint), sandbox keys pay nothing, and policy refusal semantics (max_cost_cents refuses before any debit). The destructive/mutation profile is conveyed with concrete consequences rather than just a hint.

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 core action and idempotency are front-loaded, and the policy/sandbox details follow in a compact sequence. Dense but nearly every clause earns its place; only the restated max_cost_cents phrasing is slightly redundant.

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 needn't be explained. The description covers the mutation semantics, idempotency, sandbox behavior, and error-gating policies that an agent needs to call this 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%, and the description largely restates the schema's own max_cost_cents semantics ('refuses before any debit') and batch_id provenance ('from create_batch_mail or list_batch_mail'). It adds little meaning beyond the already-complete schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Pay for a draft... and queue it for printing') and immediately clarifies the billing mechanism ('prepaid credits', 'debits exactly batch.pricing.total_cents'). An agent can distinguish this from get_batch_mail/create_batch_mail without opening either schema.

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

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

Explicit precondition ('Only after the person has seen the proof'), explicit policy gates (approval-required keys cannot pay, max_daily_pieces, max_cost_cents), and a named alternative path for sandbox ('poll get_batch_mail until submitted and use advance_test_batch_mail'). When-to-use, when-not, and alternatives are all present.

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: nothing is charged at creation, malformed rows and duplicates are skipped and listed, the proof link expires in one hour, approval-requiring keys save a draft the owner pays for, and marketing_mail is not open until the USPS permit is active. It also flags that scans store counts and times only, a privacy-relevant behavior not in 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?

One very long single paragraph stitched with semicolons, mixing workflow, pricing, QR semantics, stock options and mailing-class rules into an undifferentiated block. Much of it (stock +85¢, insert_stock options, mailing_class definitions) restates schema descriptions verbatim, so length is not fully earned and key routing information is buried mid-paragraph.

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

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

Covers the hard parts for a 23-parameter, high-stakes creation tool: prerequisites, exclusivity of input modes, per-piece QR behaviors with webhook names, minimum quantities and the required confirm step. Output schema covers the return shape, and the description still notes the result carries exact price, first recipients and image warnings.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter rules the schema cannot express: template_url vs message mutual exclusion on letters, recipients vs recipients_url exclusivity, template pixel sizing at the mail type's dimensions, and the {{tag|text}} fallback for field kits. It slightly over-explains qr modes that the schema already documents in detail.

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?

Opens with a precise verb+resource+scope: 'Create a batch draft from a template link and a recipient list; nothing is charged.' That immediately separates it from confirm_batch_mail (which charges) and send_outbound_mail (single piece). An agent can pick it without opening the schema.

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

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

Spells out the full downstream sequence: create draft → get_batch_mail_proof → hand proof_url to the person → confirm_batch_mail charges credits, plus the get_mailbox_md prerequisite and the approval-key fallback. It also states the volume gates (postcards from 1 with a $2 fee under 10; letters/flyers/pamphlets from 10; max 10,000).

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

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

The description adds substantial behavior beyond the annotations: the record is always test_mode=true, cost_cents=0, includes estimated_live_cost_cents and cost_breakdown, and queues a mail.submitted webhook. It also explains pricing behavior and the sandbox-key requirement, which is exactly the kind of context annotations alone do not provide.

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

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

The first sentence is clear and front-loaded, but the description is heavily bloated with pricing details that are already repeated in the parameter schema. Many sentences do not earn their place in the tool description because they duplicate structured field descriptions rather than helping an agent select or invoke 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 that an output schema exists and annotations cover safety traits, the description is complete enough for correct invocation: it explains sandbox mode, zero real cost, estimated cost breakdowns, webhook behavior, and the need for a sandbox key. No important operational gap is apparent.

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

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

Schema description coverage is 100%, so the input schema already documents all 12 parameters in detail, including enums and defaults. The description repeats much of that pricing and mail-class information rather than adding new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: create a sandbox outbound mail record without uploading a real document. It clearly scopes the tool to test mode and contrasts it conceptually with sending real physical mail, though it does not name the production sibling send_outbound_mail explicitly.

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 usage context: use with a sandbox key to rehearse outbound workflows before sending real physical mail. The implication is that this is for test/sandbox use only, but explicit when-not-to-use guidance and named alternatives are not 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?

Goes well beyond the annotations: endpoint is active on save, the whsec_ secret is returned exactly once and must never be logged or sent in mail, the control plane and tenant/agent/Live-Sandbox authorization model is named, and the retry semantics for uncertain mutations are spelled out. Annotations only cover idempotency/read-only hints, so this adds substantial 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?

Front-loaded with the create action and its inputs, then layers constraints. It is dense but every clause carries operational weight; the auth-scoping and control-plane sentences could be trimmed without loss.

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 covering safety/idempotency, the remaining burden is permissions, secret handling, scoping and retry behavior — all addressed. An agent has what it needs to invoke this correctly without further docs.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the rule shape (literal terms, any/all, exclusions) and the agent_id/environment scoping already documented in the schema, and notably lists only the five inbound event types while the schema supports 19 — so the description adds little and is slightly narrower than the schema.

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

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

States a specific verb and resource ('Create a webhook') and immediately enumerates the defining inputs (name, public HTTPS URL, events, keyword rules), which separates it from update_webhook_endpoint and list_webhook_endpoints in the sibling set.

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 preconditions: 'Requires explicit user intent for the URL', 'Requires webhook.manage', agent vs member key scoping, and 'Reuse the exact idempotency_key and input after an uncertain mutation'. It lacks an explicit contrast with update_webhook_endpoint (when to create vs when to modify), so it stops short of full alternative routing.

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, and openWorldHint annotations, the description adds substantial behavioral context: the estimate is the exact amount confirm debits, a per-piece minimum floor applies, volume discounts stop at that floor, and sandbox keys return credits_required_cents 0. It also discloses that Marketing Mail is unavailable until the facility's USPS permit is active.

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 purpose is front-loaded, followed by organized pricing details by class and piece type. The prose is dense and long, but the pricing clauses earn their place by enabling accurate cost interpretation; it stops short of being maximally 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?

Given an output schema, read-only annotations, and 100% schema coverage, the description fills the remaining gaps: eligibility thresholds, pricing model, discount behavior, minimum floor, exact-debit guarantee, and sandbox behavior. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds pricing semantics not captured in the schema, including color-page costs, duplex inclusion, volume discount thresholds, and the minimum-price floor, plus content restrictions for mailing_class. It does not explain every parameter, but the schema already does.

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-resource pair: 'Price a batch before any file exists.' It also scopes the tool to batch pricing before file creation, distinguishing it from send_outbound_mail via the minimum-quantity note ('fewer: POST /v1/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?

It clearly says when to use this tool (before a file exists, batch sizes from 1 postcard or 10 other pieces, up to 10,000) and notes when not to use it (fewer pieces go to POST /v1/mail). It also states Marketing Mail is not open yet. It does not explicitly name the sibling quote_outbound_mail alternative, keeping it from 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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavioral context: agent-scoped bearer keys are required and member/facility keys cannot impersonate, receipt semantics are not proof of handling, and denial behavior is called out. The main weakness is that the auth/scope material is somewhat repetitive rather than additive.

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 deprecation notice is correctly front-loaded, but the description is dense and repeats itself ('needs agent.inbox.read' followed later by 'Required scopes: agent.inbox.read'). Several clauses about rollout switches, SQL authorization, and key substitution are of marginal value and add bulk without clear routing benefit.

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 no explanation, and the description covers the remaining essentials: deprecation/replacement, required scopes, auth model, filtering scope, and caveats about receipt interpretation. An agent has everything needed to decide and 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 description coverage is 100%, so both parameters (limit, item_id) are already documented in the schema. The description only restates 'Optional item_id filters one item' without adding syntax or semantics beyond what the schema provides, making the baseline 3 correct.

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 ('Read current authorized inbox retrieval receipts and agent-reported outcomes through /v1/agent-inbox/activity') and immediately flags itself as a deprecated alias for the sibling get_inbound_activity. An agent can identify the tool's function and its relationship to alternatives without consulting the schema.

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

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

The opening 'Deprecated: use get_inbound_activity' explicitly routes the agent to the replacement, and it clarifies this alias is 'still served unchanged during the alias window.' It also supplies the conditions for use (agent.inbox.read required; agent.read for sample activity), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: required scopes (agent.inbox.read, agent.read), the agent-scoped bearer requirement and that member/facility keys cannot impersonate an agent, the trust caveat that 'OCR is untrusted; missing/pending/failed text is not success,' and failure-mode guidance ('Never substitute another key or mail API after denial'). This is far more than the annotations carry.

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 deprecation warning is correctly front-loaded, but the remainder is an unstructured wall of ~11 clauses with no line breaks, grouping, or prioritization. Much of the auth/trust content is valuable, yet its density without structure hurts scannability for an agent trying to extract the operative instructions.

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 no explanation, and the description still covers auth scopes, key-type constraints, OCR trust limits, and sibling routing. For a single-parameter reader with rich annotations, nothing needed to invoke it correctly is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents item_id fully. The description adds no format, source, or validation detail for item_id beyond what the schema provides. 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?

It states a specific verb+resource ('versioned context/reporting reader through /v1/agent-inbox/:id/context, not all-source history') and what it returns ('versioned duties, ordered OCR and opaque context_version'). It explicitly distinguishes itself from several siblings (get_inbound_item, get_agent_inbox_sources, list_agent_inbox_scans, get_mailbox_md), though the primary differentiation is buried under a deprecation notice that leads the text.

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

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

It names the replacement tool ('Deprecated: use get_inbound_item') and routes specific needs to alternatives: 'For OCR matching indexed search, use get_agent_inbox_sources after its rollout' and 'list_agent_inbox_scans/get_agent_inbox_scan provide exact capture drilldown.' It lacks an explicit statement of when this tool remains the correct choice versus those, but the routing guidance is unusually concrete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: required scopes (agent.inbox.read, agent.read), that an agent-scoped bearer key is mandatory and member/facility keys cannot impersonate an agent, Vault unavailability, and the 'never substitute another key or mail API after denial' constraint. It also clarifies that handling version differs from OCR context_version. This is rich behavioral disclosure.

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

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

The deprecation and purpose are correctly front-loaded, but the body is a dense run-on that mixes high-value facts (scopes, key restrictions) with low-signal implementation trivia such as 'Rollout switches, current member approval, assignment, credential environment and SQL authorization are shared with REST.' For a one-parameter read tool the prose is oversized and could be tightened.

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

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

An output schema exists, so return values need not be explained. Given the tool's complexity, the description covers auth model, scoping, deprecation status, version semantics and constraints — enough for an agent to invoke it correctly and know when not to.

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

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

Schema coverage is 100% with a single required UUID parameter already fully documented in the schema. The description only echoes the path id via ':id' and adds no format or sourcing nuance beyond 'from a list or search result' already present in the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Read /v1/agent-inbox/:id/handling capabilities, version and history.' This clearly distinguishes it from siblings like get_agent_inbox_activity, get_agent_inbox_context and get_agent_inbox_scan. The deprecation banner front-loads a redirect to get_inbound_item, which slightly muddies but does not obscure the purpose.

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

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

Explicitly names the alternative ('Deprecated: use get_inbound_item. Still served unchanged during the alias window') and scopes applicability ('Gated private-mail Live and member-sample Sandbox workflow only; no generated fixtures or managed-PMB fallback'). That is strong when-to-use routing, though it does not describe the window's end condition or a fallback beyond the alias.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: required scopes (agent.inbox.read, agent.read), agent-scoped bearer key requirement, prohibition on member/facility key impersonation, absence of image URLs/OCR trigger/retry/receipt, the untrusted-text warning, and the honesty expectation for null/queued/processing/failed/needs_review states.

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 deprecation and successor, then ordered by operational concern (identity of the resource, key/scope, id semantics, verification, exclusions). It is long and dense, but nearly every clause carries distinct operational information; only minor tightening is possible.

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 described, and the description fully covers what remains: deprecation window, auth/scope preconditions, id provenance, status honesty, exclusions, and the untrusted-data caveat. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real semantics: request_id must be the REST operationId from list_agent_inbox_scans rather than a page or bundle ID. That disambiguates which id type is expected in a way the schema alone does not.

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 ('Read one exact completed facility capture and its saved page OCR'), names the exact endpoint path, and immediately flags deprecation with the successor get_inbound_pages. An agent can distinguish this from get_inbound_pages, list_agent_inbox_scans, and get_agent_inbox_activity without opening any schema.

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

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

Explicit routing in both directions: deprecated in favor of get_inbound_pages, use get_mailbox_md for full effective duties, do not acknowledge via report_agent_inbox_outcome. It also pins the correct id source ('Use request_id from list_agent_inbox_scans as the REST operationId, not a page or bundle ID'), which is exactly the when/how guidance an agent needs.

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 readOnly/idempotent/non-destructive, but the description adds substantial context beyond them: required scopes (agent.inbox.read + agent.read), agent-scoped bearer key with no member/facility impersonation, rollout/assignment gating, Retry-After and jitter guidance, and explicit side-effect boundaries (no acknowledgment version, receipt, provider call, signed image URL, or charge). It also clarifies that pagination is a current view, not a snapshot.

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?

It is front-loaded with the critical deprecation notice, but at roughly 330 words for a three-parameter read tool it is heavily oversized and reads as a run-on of fragments covering custody models, rollout switches, and unrelated exclusions (managed-PMB, forwarded email) that the caller does not need. Scopes are stated twice ('plus agent.inbox.read + agent.read' and 'Required scopes: agent.inbox.read, agent.read; Both read scopes required'), which is pure 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 outputSchema present, field meanings and sort order are correctly delegated to it, and the description still covers everything else an agent needs: permissions, rollout prerequisites, pagination model, retry policy, and result-sharing constraints. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: item lists page via next_offset while sources/scans use has_more plus offset+returned length, and it states the hard 10000 cutoff that the schema only encodes as a numeric maximum. It adds value while still restating some bounds already in the schema.

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

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

The description gives a concrete verb+resource (the OCR source read for an inbound item, GET /v1/agent-inbox/:id/sources) and positions it relative to siblings: it follows list_agent_inbox and is deprecated in favor of get_inbound_item. That is enough to tell it apart from the other inbox/mail tools. The deprecation notice, however, muddies whether an agent should call it at all, keeping it short of a 5.

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 routing is provided: use get_inbound_item instead, otherwise call this after list_agent_inbox, narrow by item_id and date window rather than polling whole mailboxes, and fetch only selected items. It also states when to stop (before offset 10000, or report incomplete history) and how to handle 429/transient failures, which is unusually complete 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real behavior beyond that — the status lifecycle chain, default page size of 50, and the fact that the same events are pushed to the webhook. It omits things like auth requirements or rate limits, so it's strong but not exhaustive.

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

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

The purpose is front-loaded and most clauses earn their place, packed efficiently into a dense description. It is a long, heavily parenthesized run-on and ends with a trailing REST path that adds little, which keeps it from a 5.

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

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

For a read tool with a full input schema plus an output schema, the description already over-delivers on return shape, status semantics, pagination, and webhook interplay. 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 coverage is 100%, so baseline is 3; the description still adds value by explaining the qr filter semantics in context ('the pieces scanned, confirmed (verify: the address verified) or not_scanned') and how offset/limit page through pieces. It doesn't deepen the batch_id parameter beyond what the schema already says.

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?

It names a specific verb and resource ('a batch with its status ... recipient summary, pricing, tracking...'), so an agent immediately knows it fetches a single batch-mail batch with full detail. It stops short of naming the obvious siblings it should be distinguished from, e.g. list_batch_mail and get_batch_mail_proof, which would make the boundary 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?

'Poll it after confirm' gives explicit timing guidance tied to the confirm_batch_mail step, and it notes that batch.submitted / batch.completed also arrive on the webhook, which is a genuine alternative path. It doesn't state when *not* to use it (e.g. to list batches or to fetch proof artifacts), so it falls short of full when/when-not coverage.

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 a safe, idempotent read, but the description adds what annotations cannot: the link expires in one hour, requires no key, and opens in any browser or IDE, plus that the record also returns label lines as text. The parenthetical contrasting links.proof as the API-key-required route preempts a likely wrong turn.

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 workflow instruction is front-loaded and the parenthetical caveat is well-placed. The first sentence is long and packs a list of PDF components that borders on over-specification, but every clause conveys something about the artifact being returned.

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 no prose, and the description still notes the label lines come back as text. Sequencing, expiry, auth-free access, and a disambiguation from the sibling route are all covered — nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so batch_id and the 1-based recipient are already documented in the schema. The description reinforces 'recipient N's piece' but adds no format, default, or validation detail beyond what the schema states. Baseline 3 is appropriate.

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

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

The description concretely enumerates what the proof contains (PDF of the template as recipient N's piece prints, QR code, sample code, insert, plus the address label at real size) and explicitly contrasts it with the sibling-adjacent 'links.proof on the batch'. The verb is only implied, but the resource and its contents are unmistakable and no agent would confuse this with get_batch_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 sequencing: 'Call it after create_batch_mail and give the person proof_url before confirm_batch_mail' tells the agent exactly where this sits in the workflow. It also names the alternative route (links.proof) and the condition that distinguishes them — that route needs the API key, this one does not.

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 declare readOnly/idempotent/non-destructive, but the description goes well beyond them: a row proves recording only, not OCR accuracy or physical completion; proposals are agent-only and never charge credits, buy postage, open, forward or discard; forwarding/discard proposals are checked against the inbound policy; image URLs are never issued to agents; stop on denial rather than switching keys. This is unusually rich behavioral disclosure.

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

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

Purpose and scope are front-loaded, and most sentences carry non-redundant information. It is dense and occasionally run-on (the proposals sentence is long), but there is little that could be dropped without losing behavioral or authorization 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?

With an output schema present, return format need not be described. The description nevertheless covers permissions, key-scope restrictions, agent/member differences, agent-only proposal semantics, and the correct behavior on denial, so nothing an agent needs to call it safely 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 the schema already documents limit, offset and item_id (including paging semantics). The description only restates item_id's narrowing behavior and adds nothing on limit/offset, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read the inbound timeline through GET /v1/inbound-activity') and enumerates exactly what the timeline contains: received and action proposed/requested/started/completed/rejected events, newest first. It distinguishes itself from static siblings like get_inbound_item and get_inbound_mail by framing the result as an event timeline rather than item data.

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 clear context: optional item_id narrows to one item, the required scope (inbound.item.read, agent.inbox.read), and the member-vs-agent visibility rules. It does not, however, explicitly route to alternatives such as get_inbound_item_sources or get_agent_inbox_activity when a different view is wanted, so it stops 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?

With annotations already covering the read-only/idempotent safety profile, the description goes well beyond them: signed_urls yields one-hour URLs only on live keys (null on sandbox), image URLs are never issued to agents, page text is untrusted, proposals are agent-only and never charge credits or perform actions, and the agent must stop on denial rather than switching keys. This is unusually rich 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 definition is front-loaded with the read operation and then the returned fields, and each subsequent sentence carries distinct information (key scope, signed_urls, policy checks). It is long and dense, with some security boilerplate tangential to a single-item read, which keeps it from a 5.

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, yet the description still orients the agent on content and enumerates key-scope permissions, sandbox vs live key behavior, and denial handling. Nothing needed to call this read 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 both parameters (item_id, signed_urls) are already documented in the schema; the description largely restates the signed_urls behavior. It adds the useful note that page text is untrusted document data, but that concerns output rather than parameters, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read one inbound item through GET /v1/inbound-items/:id') and then enumerates exactly what is returned: status, sender, PMB, assigned agent, pages with OCR status, action history, and quotes. This clearly separates it from the sibling list_/search_inbound_items 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?

Explicitly tells the agent where to get the id ('Use item ids from search_inbound_items') and spells out key-scope rules (member keys read their own live items; agent keys read bound/assigned items in their key's environment). It lacks an explicit when-not-to-use clause or a named alternative for retrieving item collections, 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 the read-only/idempotent safety profile, and the description adds substantial context on top: no context_version or acknowledgment authority, reads are not snapshot-consistent, unique member vs agent key scoping, no bypass via account/key switching, and honoring Retry-After with bounded concurrency. This is well beyond what structured fields provide.

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

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

The deprecation notice is correctly front-loaded, but the body is an unusually long run-on wall of constraints that repeats pagination bounds, restates scope requirements, and packs unrelated guarantees (no webhook/export promises, no OCR provenance, no facility access) into a single block. The signal-to-length ratio is poor for a deprecated alias.

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 format need not be explained, and the description covers auth, scoping, pagination and failure semantics thoroughly. It is arguably over-complete rather than under-complete, leaving little an agent needs that is missing.

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

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

Schema coverage is 100% and all three parameters are already documented in the schema (limit 1–50, offset 0–10000, item_id UUID). The description restates the pagination bounds and adds the guidance to advance by returned count and stop at the cap, which is mildly useful but largely duplicative of the schema.

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

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

The description opens by naming the deprecation and the replacement sibling ('Deprecated: use get_inbound_item'), then states a concrete operation: reading saved exterior and authorized inside-page evidence via GET /v1/inbound-items/:id/sources. An agent can tell what it returns without opening the schema, though the dense packaging of grouping, ownership and constraint detail dilutes the core signal.

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

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

It names the alternative and the condition selecting it (deprecated alias, use get_inbound_item), and specifies prerequisites for the call itself: saved-document reads enabled, an active eligible managed mailbox, and both inbound.item.read and inbound.item.scan.read. It stops short of enumerating when-not scenarios beyond the deprecation routing.

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?

Adds substantial behavior beyond the readOnly/idempotent annotations: signed_urls are one-hour and live-key-only with sandbox always returning url:null, image URLs are never issued to agents, keys are scoped by environment and ownership, and denial should halt rather than trigger key/API switching. This is far more context than the annotations carry.

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 operation and page kinds, but tails into policy text about proposals, forward destinations, discard policy and key-switching that pertains to other tools rather than reading pages. Several sentences do not earn their place for this specific read operation.

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?

Auth scope, ownership rules, pagination ('advance by the number returned'), and page field semantics are all covered, and an output schema exists so return values need not be explained. The description nonetheless describes returned fields (ocr_status, text, is_blank, uncertain_spans), which is slightly redundant but harmless; completeness is high.

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

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

Schema description coverage is 100%, so the schema already documents kind, limit, offset, item_id and signed_urls. The description restates kind and signed_urls semantics with little added syntax beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read an item's scanned pages') plus the endpoint, and explicitly enumerates the three page kinds (exterior, interior, evidence) with their triggering conditions. An agent can distinguish this from list/search siblings without opening a schema.

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

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

Gives rich context: interior pages only exist after a completed Open & scan, member vs agent key scoping, environment binding, and the read scope required. However it never names an alternative sibling (e.g. get_inbound_item or get_agent_inbox_scan) or states when NOT to use this tool, 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?

The annotations already declare this as a safe, idempotent, non-destructive, non-open-world read, so the safety burden is lifted. The description adds a genuinely useful behavioral nuance beyond the annotations: the PMB number only exists after USPS Form 1583 verification, implying the value may be pending. It stops short of stating what is returned when verification is incomplete, but the output schema covers return shape.

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

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

Front-loads what the tool returns and follows immediately with the routing rule, which is the right ordering. However, the second sentence is a run-on and repeats 'from addresses the operator already uses' twice, a redundancy that could be trimmed without loss.

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. Annotations carry the safety/idempotency profile, there are no parameters to document, and the description supplies the two things structured data cannot: the USPS Form 1583 gating caveat and the sibling routing rule.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No misleading or missing parameter guidance is present.

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+resource ('Get your agent's real mailing address') and enriches it with concrete detail: street address plus PMB at the Manhattan Beach, CA facility. It also names the sibling it is not (list_inbound_forwarding_addresses), so an agent can route correctly without opening either schema.

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

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

Explicitly gives the alternative and the condition that selects it: inbound context from operator-used addresses goes to list_inbound_forwarding_addresses instead. The agent knows both when to use this tool and when to switch, with no inference required.

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 cover the read-only/idempotent safety profile, and the description adds substantial context beyond that: required scopes (agent.inbox.read, plus agent.read for nonempty q), the agent-scoped bearer-key constraint (member/facility keys cannot impersonate), the 10000 pagination cap with incomplete-results caveat, sandbox-vs-live data differences, and that no fuzzy search or new OCR occurs. This is rich behavioral disclosure that the annotations alone do not provide.

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

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

The deprecation warning is front-loaded, which is the single most important fact. However, the body is a dense run-on of semicolon-linked clauses combining search semantics, rollout gating, credential rules, and pagination, so it is less scannable than it could be. Nearly every clause carries needed information, so little 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?

For a 5-param, 0-required read tool with an output schema present, the description covers everything an agent needs: deprecated status, routing to the replacement and to get_agent_inbox_sources for follow-up reads, auth/scope requirements, pagination limits, and the fact that results are metadata not text. No material gap remains.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic detail: q is literal AND over IDs/metadata/authorized OCR with a 12-term cap and additionally needs agent.read; received_after is inclusive / received_before exclusive and require the rollout plus both read scopes; sender keywords go through q, not an invented field. It clarifies scoping and normalization beyond the schema.

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

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

States a specific verb+resource ('List/search current assigned postal mail') and immediately distinguishes itself from the sibling it is deprecated in favor of: 'Deprecated: use search_inbound_items.' The scope ('same /v1/agent-inbox service') and behavior ('returns metadata, not text') are explicit, so an agent can tell it apart from get_agent_inbox_sources or search_inbound_items without opening a schema.

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

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

Gives explicit when-to-use guidance ('Deprecated: use search_inbound_items. Still served unchanged during the alias window'), names an alternative for follow-up ('Read selected matches using get_agent_inbox_sources after indexed rollout, not the original sample /context'), and specifies the alternative explicitly. When/when-not and alternatives are all present.

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, idempotent, non-destructive, closed-world), yet the description adds substantial behavior beyond them: required scopes (agent.inbox.read, agent.read), agent-scoped bearer key requirement, pagination cap at offset 10000 with incomplete-history reporting, OCR status semantics ('completion is not extraction success'), and that no provider/retry/ack is triggered. This is exactly the extra context annotations cannot carry.

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 correctly with the deprecation notice, and most sentences carry real information (auth, caps, OCR caveats). However the body is a dense, run-on block with some redundancy against the schema, which reduces scannability despite the substantive content.

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

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

An output schema exists, yet the description still states the return shape (request_id, bundle_id, page count, OCR status, not text) and full auth/pagination/rollout context. Nothing an agent needs to invoke this 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 the schema already documents q, limit, offset and item_id in detail. The description largely restates q's normalization/max-length/AND semantics that already live in the schema, adding little beyond what is structured. Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource+scope: 'List/search completed facility-captured scan jobs for this assigned member sample' at the exact endpoint /v1/agent-inbox/:id/scans. It distinguishes itself from siblings by naming the replacement (get_inbound_pages) and the singular counterpart (get_agent_inbox_scan) implicitly through 'completed... scan jobs'.

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?

Opens with 'Deprecated: use get_inbound_pages. Still served unchanged during the alias window,' giving explicit when-to-use and the alternative. It further constrains usage with 'Sandbox agent key only' and 'after indexed rollout, item search also includes these captures,' which tells the agent exactly when this tool is the right call.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile needs no restating. The description adds genuinely non-obvious context: results are key-scoped, with sandbox keys seeing only sandbox batches and agent keys only their own agent's batches. It stops short of describing pagination traversal or result volume.

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 compact sentences with no filler; the ordering and scope information comes first, and the key-type nuance follows. Every clause carries information an agent would otherwise have to guess.

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 a full output schema and rich annotations, the description only needs to cover access scoping — which it does — and ordering. The one remaining gap is pagination semantics (offset-based traversal, no total-count hint), which is minor given the schema documents limit/offset.

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% — limit, offset, and status are each documented, and status has an enum. The description adds nothing param-specific beyond the 'newest first' ordering note, so the baseline 3 applies when the schema carries the parameter burden.

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 fragment "The caller's batches, newest first" combined with the name clearly identifies a collection-listing operation over batch mail, including scope (caller's own) and ordering. It does not explicitly distinguish itself from siblings like get_batch_mail (single fetch) or list_outbound_mail, but the resource 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?

The sentence about sandbox keys vs agent keys tells an agent what it will see, which implicitly frames when the tool is appropriate. However, there is no explicit 'use this instead of X' guidance against get_batch_mail or list_outbound_mail, and no stated preconditions for calling 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 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 cover read-only, idempotent, non-destructive, and non-open-world traits. The description adds substantial operational context beyond that: no extraction/retry/provider calls, independent activation of exterior/inside-page extraction, pagination behavior, non-snapshot consistency, concurrency/backoff/Retry-After guidance, and key scoping rules. No contradictions with annotations.

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

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

The description is a dense wall of text far longer than needed for a deprecated alias. It repeats schema-level details (limit/offset, q constraints) and piles on warnings. While the deprecation notice is front-loaded, the overall size is not appropriately concise and many sentences could be trimmed or moved to external docs.

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, rich schema, annotations, and output schema, the description is highly complete. It covers auth scopes, key scoping, pagination, data freshness, failure handling, and limitations. Nothing critical for correct invocation appears missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds useful meaning: q matches across metadata and multiple OCR layers and may hit different pages; received_after/before filter intake time not printed dates; sender/address should be identified from page evidence. These additions go beyond the schema, though some points are redundant.

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

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

The description clearly states it is deprecated in favor of search_inbound_items and describes the tool as searching managed-renter physical mail via a specific endpoint. The verb+resource are identifiable, and it distinguishes itself from the named replacement sibling. However, the name says 'list' while the description uses 'search', which creates minor tension.

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

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

Explicitly tells the agent to use search_inbound_items instead, notes this is only for the alias window, names get_inbound_item_sources for selected items, and lists prerequisites (saved-document reads enabled, eligible managed mailbox, required scopes). It also states exclusions (no facility/Sandbox/package.read) and denial handling.

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 establish read-only, idempotent, non-destructive behavior, and the description adds substantial context: a 50-delivery limit, excluded payload fields, 2xx semantics, permission requirements, and authorization boundaries. The idempotency_key sentence is oddly placed for a read tool but 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 key purpose is front-loaded and the payload/security constraints are useful, but the description is dense and includes an irrelevant instruction to reuse idempotency_key after an uncertain mutation. That sentence does not earn its place in a read-only delivery listing 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 a simple one-parameter read tool with an output schema and safety annotations, the description is complete: it covers scope, payload exclusions, limits, permissions, authorization model, and documentation. Return formatting does not need further explanation because an output schema exists.

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

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

There is only one parameter and schema description coverage is 100%, with endpoint_id already documented as a UUID from list_webhook_endpoints. The description reinforces 'for one webhook' but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource: read the latest 50 deliveries for one webhook. It also scopes the payload contents and makes clear this is per-webhook delivery inspection rather than endpoint listing or replay.

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 prerequisites such as webhook.manage and authorization context, but it does not explicitly say when to use this versus list_webhook_endpoints, replay_webhook_delivery, or test tools. Usage is therefore implied rather than fully guided.

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?

Valuable additions sit on top of the annotations: the webhook.manage scope requirement, the no-secrets redaction, and the tenant/agent/Live-Sandbox authorization model. However, the sentence "Reuse the exact idempotency_key and input after an uncertain mutation" is nonsense for a zero-parameter read tool and risks making the agent think it is a mutation. That boilerplate weakens an otherwise useful disclosure.

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

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

It is front-loaded well: field list first, then scope and auth, then docs. But the idempotency retry sentence earns no place for a read-only zero-param call, and the API-path and docs-link sentences crowd out more useful information about when to use this.

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 still names a few. Auth scope, redaction, and the legacy-callback boundary fill the main gaps for a simple list tool. Only the relationship to the webhook deliveries and mutation siblings is missing.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description instead spends its effort on what is returned, which is the right place for a zero-arg list tool.

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 ("List the member's webhooks") and enumerates the returned fields (name, URL, events, keyword rules, status), so the agent knows exactly what it gets. It also draws a boundary against a nearby concept: "Legacy agent callback settings are separate." That is enough to distinguish it from create/update/rotate/deliveries siblings.

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

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

The exclusion of legacy agent callback settings and the "without secrets" scope are real usage signals, but when to choose this over list_webhook_deliveries or the get/update siblings is never stated, and no alternatives are named. The context is implied rather than prescribed.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds substantial context beyond them: required scopes (agent.inbox.read, agent.read, agent.inbox.propose), agent-scoped bearer key requirement, human-approval gate before facility action, non-destructive self-limits, and idempotency replay/refusal semantics. This is rich behavioral disclosure that an agent could not infer from structured fields.

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 deprecation notice is front-loaded and nearly every clause carries actionable information (scopes, approval, idempotency, non-substitution). It is dense and long, bordering on overstuffed, but avoids filler and 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?

For a mutation-style proposal tool with an output schema and full annotations, the description covers the remaining gaps an agent needs: auth model, scopes, approval flow, idempotency contract, and failure/recovery behavior. Nothing required to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: forward_original requires a complete US destination and mail class, discard_original needs subsequent owner/staff confirmation, and expected_version/idempotency_key must be reused identically after uncertainty. This goes beyond the schema's own property 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 verb+resource are clear ('Propose... handling' via /v1/agent-inbox/:id/handling) and the successor tool request_inbound_action is named, which lets an agent distinguish it from siblings. However the actual purpose statement is buried under deprecation and operational text rather than front-loaded as a single clean sentence.

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 when-to-use ('Deprecated: use request_inbound_action... still served during the alias window'), prerequisites ('Read capabilities/version first'), and recovery guidance ('Reuse identical idempotency_key/body/original expected_version after uncertainty'). It also states what the tool must NOT be used for (self-approve, dispatch postage, charge, destroy) and warns against substituting another key after denial.

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?

Annotations cover the read-only/idempotent/non-destructive profile, yet the description adds substantial non-obvious behavior: sample/test items return cost_cents 0 with live_cost_cents showing the real price, proposals never charge credits or buy postage, destinations are validated against the agent's inbound policy, and denial should halt the agent. This is rich context beyond the structured fields.

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 core purpose and the chaining instruction are front-loaded, which is good, but the text runs long and mixes in tangential boilerplate (image URLs never issued to agents, never switch keys or mail APIs) that does not help an agent invoke this specific pricing 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?

With an output schema present, the description needn't explain returns, yet it still clarifies the cost_cents/billable breakdown and the sample-item case. Combined with permission scope, side-effect guarantees, and the explicit hand-off to request_inbound_action, an agent has what it needs; only error/denial handling detail is thin.

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 both parameters (item_id, postal_code) are fully documented in-schema, so the baseline is 3. The description reinforces that postal_code is a US ZIP destination but adds no format or syntax detail beyond what the schema already provides.

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

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

The description states a specific verb and resource ('Price every forwarding class for an item to a US ZIP') and even names the endpoint GET /v1/inbound-items/:id/forward-quote. It is clearly distinguishable from the sibling quote_outbound_mail, which prices outbound mail rather than inbound forwarding classes.

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 downstream usage: pick a class and pass { cost_cents, billable, max_cents: cost_cents } as action.expected_quote to request_inbound_action. It also states key-scope rules (member keys read own items, agent keys read bound/assigned items). It stops short of stating when NOT to use it versus alternatives, but the context is clear.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, yet the description adds real value: no account required, nothing is created, output is a price plus breakdown in USD, and prices reflect a new account. It does not explain whether prices are cached or subject to change, but the safety profile is fully covered.

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

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

Four tight sentences, front-loaded with the core purpose and the zero-side-effect guarantee. The final sentence ('The dry run of the real document is the exact price for an account') is slightly oblique in phrasing, costing a bit of clarity without wasting much space.

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 a rich input schema, an output schema, and full annotations, the description only needs to frame intent and side effects, which it does well. The one gap is silence on delivery_signature fees despite the schema itemizing them into cost_breakdown.delivery_signature_cents.

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

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

Schema coverage is 100% and the enum descriptions are unusually rich, so the schema does the heavy lifting. The description names mail class, page count, color and FedEx ZIP but omits delivery_signature entirely — a fee-bearing parameter an agent could easily overlook if relying on the prose. Baseline 3 is appropriate given the strong schema.

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

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

States a specific verb and resource: 'Price a letter before you have the document', and clarifies it returns mailbox.bot's published price with a breakdown in USD. The outbound/single-letter scope separates it from batch and inbound siblings only implicitly via the name, not the description text, so it misses full sibling differentiation.

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?

'Price a letter before you have the document' clearly frames the pre-purchase scenario, and 'Needs no account and creates nothing' plus the note that the real-document dry run gives the exact account price implicitly routes the agent elsewhere once a document exists. The alternative is hinted at rather than named explicitly (no mention of create_outbound_mail or estimate_batch_mail).

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

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

Adds substantial context beyond the annotations: preserves event_id for deduplication, rechecks the current endpoint revision so concurrent edits are not overwritten, requires the webhook.manage permission, and inherits the tenant/agent/Live-Sandbox authorization model of /api/v1/webhooks/endpoints. None of this is derivable from the readOnly/idempotent/destructive 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?

Purpose and scope are front-loaded in the first two sentences, with prerequisites, auth, and idempotency guidance following in a logical order. It is dense but every sentence carries actionable information, so only minor trimming is possible.

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 explained, and the description covers what an agent needs: the precondition, the exclusions, the required permission, the authorization model, the concurrency safeguard, and a docs link. Nothing material is missing for a 4-parameter mutation 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%, so the baseline is 3, but the description adds real meaning: it explains that the revision is rechecked to prevent overwriting concurrent edits and that the idempotency_key must be reused verbatim after an uncertain mutation, which goes beyond the schema's field-level text.

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 ('retry a failed delivery') and immediately narrows scope by excluding successful deliveries, so an agent can distinguish it from siblings like test_webhook_endpoint or list_webhook_deliveries. The 'explicitly' framing clarifies this is a manual operator-initiated replay rather than automatic retry.

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 a clear precondition ('after correcting the receiver') and an explicit exclusion ('Does not replay successful deliveries or approve facility handling'), plus retry guidance for uncertain mutations. It stops short of naming a specific sibling alternative, so it lands just below the top band.

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

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

Despite annotations covering idempotency and safety profile, the description adds substantial behavioral context: deprecation status, required scopes (agent.inbox.report plus read scopes), agent-scoped bearer key requirement with the explicit note that member/facility keys cannot impersonate, idempotency replay semantics, and the constraint that reports cannot approve or complete facility handling. This is well beyond what annotations provide.

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

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

Dense but front-loaded with the critical deprecation warning and the endpoint, and every sentence carries actionable information (auth, scopes, idempotency, retry rules). The run-on construction and rapid topic shifts cost it a point, but there is little true filler.

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

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

With an output schema present the description need not explain returns, and it fully covers auth model, required scopes, deprecation lifecycle, idempotency behavior, and the semantic boundary that reporting is not approval. Nothing an agent needs to invoke this 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 the baseline is 3, but the description adds meaningful qualifiers: send the exact fetched context_version, a non-sensitive run_id, and the outcome, tying context_version to its source (get_agent_inbox_context). This adds value beyond the schema's field descriptions.

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

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

States a specific verb and resource ('Report actual external-worker processing through /v1/agent-inbox/:id/acknowledgments') and immediately marks the tool as deprecated with no successor, so an agent knows both what it does and its lifecycle status. The 'actual ... processing' framing also implicitly distinguishes it from proposal-type siblings like propose_agent_inbox_handling.

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 clear usage conditions: report actual processing, never report 'processed' before doing the work, retry only the same idempotency_key, and never substitute another key or mail API after a denial. It does not explicitly name a successor or an alternative sibling, but the deprecation notice and the proposal/report distinction provide strong routing 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?

Goes well past the annotations: proposals always wait for owner approval (awaiting_member_approval: true), never charge credits or move mail, are server-side checked against inbound_policy, allow only one open action per item, and image URLs are never issued to agents. It also states the key scope (inbound.item.action / agent.inbox.propose) and failure behavior ('Stop on denial'). This is exactly the behavioral context annotations cannot express.

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 and information-dense, but it repeats itself: the 'never charge credits / never move mail' guarantee and the inbound_policy check are each stated twice. Tightening the redundant clauses would lose nothing an agent needs.

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

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

With an output schema present, return values need not be explained, and the description still covers approval flow, quote freshness, idempotency, key scope, policy enforcement, and denial handling. Nothing material for correct invocation is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics: expected_version is the item's current version, expected_quote is required for scan and forward and otherwise refused with a fresh quote, and idempotency_key must be stable across retries. The destination rules (complete US address) and mail_class default are reinforced with policy context.

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 (Propose) plus the three concrete action types (scan, forward, discard) and the endpoint that carries them, so the agent knows exactly what the tool does. It is clearly distinguishable from read-side siblings like get_inbound_item and list_inbound_items.

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 strong when-to-use context: agent-keys-only, one open action per item, expected_quote sourced from get_inbound_item quotes.scan or quote_inbound_forward, first_class requiring untracked_acknowledged, and packages not yet forwardable. It stops short of explicitly contrasting with the sibling propose_agent_inbox_handling, so the routing among proposal tools is left to inference.

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

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

Annotations already flag destructive, idempotent, and open-world behavior, and the description adds real context beyond them: a 24-hour signature overlap window, the required webhook.manage scope, the shared tenant/agent/Live-Sandbox authorization boundary, an explicit 'never expose either secret in logs or prompts' caution, and idempotent retry semantics. That is the authorization and side-effect detail an agent needs before a destructive call.

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 rotation instruction and the confirm_rotation:true gate are front-loaded, and each subsequent sentence carries operational information. A couple of clauses are dense and partly redundant (confirm_rotation:true appears in both sentence one and the schema; the control-plane authorization sentence is verbose), but there is no filler.

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

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

With an output schema present, a fully described 4-parameter schema, and rich annotations, the description covers the remaining gaps: permission requirements, destructive-window behavior, idempotent retry, and secret-handling safety. Nothing needed to invoke this correctly is missing, and a docs link is provided for deeper detail.

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 baseline is 3, but the description adds meaning beyond the schema for two parameters: confirm_rotation is gated on explicit operator authorization rather than merely being const true, and idempotency_key reuse is tied to recovering from an uncertain mutation. endpoint_id and expected_revision semantics are left entirely to the schema.

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

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

The description states a specific verb and resource ('Rotate the signing secret') and scopes it narrowly with 'the signing secret only', which separates it from sibling update_webhook/update_webhook_endpoint that presumably change other endpoint configuration. An agent can identify the operation without opening any schema.

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

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

It gives clear preconditions: explicit operator authorization, confirm_rotation:true, and the webhook.manage permission. It also covers the retry case ('reuse the exact idempotency_key and input after an uncertain mutation'). It stops short of naming an alternative tool for non-secret changes, which is only implied by 'signing secret only'.

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 a safe, idempotent, non-destructive read, and the description still adds substantial behavior beyond them: key scope semantics (inbound.item.read / agent.inbox.read), member vs agent key visibility, environment scoping, the sandbox sample dataset, the explanatory notice on empty results, the guarantee that image URLs are never issued, and the rule that proposals never charge or act autonomously. This is well past the lower bar set by 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?

It is front-loaded — the purpose and the q/filter behavior come first — but it is a dense multi-clause block that folds in unrelated policy about proposals, forwarding and discard checks against the agent's inbound policy, which belongs to the propose_* tools rather than a read/search tool. Several clauses earn their place; the policy tail does not.

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

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

Given an output schema exists, the description need not explain return values, yet it still sketches them, and it covers auth scopes, sandbox behavior, denial handling and cross-tool id usage — ample for correct invocation. The remaining gap is sibling disambiguation against list_inbound_items/list_inbound_mail.

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 largely restates what the schema already documents (q as a literal AND search with term/character limits, status/kind/date filters narrowing the set), adding only the framing that received_after/received_before refer to intake time. It adds little semantics the schema does not already carry.

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 concrete verb+resource ('List and search inbound mail through GET /v1/inbound-items') and enumerates the returned fields (public status, kind, sender line, envelope page, open action), which is specific enough to act on. It does not, however, differentiate itself from near-identical siblings such as list_inbound_items or list_inbound_mail, so an agent cannot tell from the description alone which of these to pick.

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 clear operational context: use item.id with the other tools, sandbox keys should start with q: "Mojave", and 'Stop on denial; never switch keys or mail APIs to bypass it.' It explains how filters narrow results and when an empty result is expected. What it lacks is an explicit when-to-use-this-vs-alternatives statement naming the sibling list/search tools.

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

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

Annotations only flag write/idempotent/non-destructive; the description adds substantial context beyond them: required scope agent.inbox.read, agent-scoped bearer key requirement, that member/facility keys cannot impersonate an agent, idempotent replay semantics, and a deprecation timeline. This is exactly the extra behavioral detail annotations cannot carry.

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 deprecation notice is correctly front-loaded, but the body is a dense run-on of eight clauses, including opaque context such as 'rollout switches, current member approval, assignment, credential environment and SQL authorization are shared with REST' that does little to help tool selection. Information-dense but not tight.

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 explain return values, and it covers everything else an agent needs: auth/scope requirements, key-scoping rules, idempotency behavior, deprecation status, and the negative space of what the fixture does not do.

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 both parameters (scenario enum, idempotency_key pattern/length) are fully documented in the schema. The description restates the replay-key reuse rule but adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('seed') and resource (an isolated provider-free two_page_letter or needs_review fixture) via a named endpoint /v1/agent-inbox/sandbox/seed. It also distinguishes itself from siblings by declaring that these fixtures test reads/reports, not handling, and that no real mail/model call/email/facility task is involved.

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 clear conditions: sandbox agent key only, deprecated with no successor but still served until the alias window closes, and an explicit 'never substitute another key or mail API after denial' exclusion. It does not name which sibling tool to use for the handling scenarios it disclaims, so it stops short of full alternative routing.

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.