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

Goes well beyond the annotations by disclosing concrete side effects: completion 'marks every piece mailed' and 'fires batch.completed to the agent's webhook.' Those effects are invisible from the annotation set, which only says non-readonly, non-destructive, non-idempotent — the webhook emission and bulk state mutation are exactly the context an agent needs before calling.

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, zero padding, with the hard constraint ('Sandbox keys only') front-loaded before the mechanics and the live-vs-sandbox exclusion last. Every clause carries information.

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

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

An output schema exists, so return values need not be described, and the one parameter is fully covered by the schema. The description supplies the state-machine semantics, the side effects, and the sandbox-only restriction — everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100% and the single batch_id is already documented with its provenance (from create_batch_mail or list_batch_mail), so the description has little to add. It does implicitly convey that batch_id identifies a sandbox batch subject to a one-step transition, which is mild added meaning beyond the field type.

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 (simulate/advance) applied to a specific resource (the test batch), and spells out the exact state machine: submitted → in_progress → completed. It also draws the boundary against the live path ('Live batches are advanced by the facility, never by the API'), so an agent can distinguish this sandbox-only tool from the live batch 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?

'Sandbox keys only' is an explicit precondition, and 'Live batches are advanced by the facility, never by the API' is an explicit exclusion. What's missing is naming the counterpart tool (e.g. advance_test_outbound_mail for single outbound pieces), so an agent must infer from the sibling list which test-advance tool applies.

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?

Annotations declare non-read-only, non-idempotent and open-world, but the description adds substantive behavior: no charge at draft time, malformed rows and duplicates are skipped and listed rather than failing, an approval-requiring key saves the draft for the owner to pay, and the proof link expires after an hour. It even discloses pricing thresholds (a $2.00 small-batch fee under 10 postcards).

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

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

Front-loaded with the core action and the no-charge fact, then layers in constraints, but it is a single dense block of semicolon-joined clauses. Most content earns its place, though the postcard-design pixel arithmetic is a slight tangent that could be trimmed.

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 17 parameters, nested recipient objects, an output schema and existing annotations, the description still covers the missing pieces: prerequisites, the downstream proof/confirm flow, recipient-count minimums, and what the result contains. Nothing an agent needs to invoke this correctly is absent.

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 goes further by explaining template_url constraints (public https, size-matched PDF or PNG/JPG graphic, design dimensions at 300 dpi) and that 'company' is accepted as a recipient key. It stops short of documenting the return_* defaults or duplex/color semantics, which live only 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 ('Create a batch draft from a template link and a recipient list') and immediately scopes it against the charging step ('nothing is charged'), so an agent can distinguish it from confirm_batch_mail and estimate_batch_mail 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?

Explicitly chains the workflow: create the draft here, then call get_batch_mail_proof and give the person its proof_url, then confirm_batch_mail charges credits. It also states the inline-vs-recipients_url exclusion ('Send this or recipients_url, not both'), the prerequisite (mailbox_md_version from get_mailbox_md), and the approval-key path.

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

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

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

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

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

The description is very long and repetitive, with the same color-pricing text appearing multiple times in the schema and again in the description. While it contains useful pricing and behavioral details, it is not concise and could be significantly streamlined without losing essential information.

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

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

The description covers the tool's purpose, sandbox behavior, cost simulation details, carrier-specific adjustments, and webhook side effects. It is complete enough for an agent to decide when and how to use this tool, though the excessive repetition makes it harder to parse quickly.

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

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

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

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

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

The description states a specific action ('Create a sandbox outbound mail record') and clearly distinguishes it from sending real physical mail, explicitly noting it is for rehearsing outbound workflows with a sandbox key. This provides strong purpose clarity and differentiates it from sibling tools like send_outbound_mail.

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

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

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

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

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

Goes well beyond the annotations: it discloses that the endpoint is active on save, that the whsec_ signing secret is returned exactly once and must go only to the operator's secure config and never into logs or mail content, and that authorization follows the same bounded control plane and tenant/agent/Live-Sandbox model as the HTTP API. This is exactly the kind of consequence and safety 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?

The most important facts are front-loaded in the opening sentence, and the later sentences on the secret, permissions and idempotency each earn their place. It is somewhat dense and partially re-states event names already enumerated in the schema, which keeps it from being maximally 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?

For a 7-required-parameter mutation with an output schema, the description covers the remaining unknowns: permissions, tenant/environment scoping, one-time secret handling, idempotent retry behavior and a docs link. Return values need not be explained because the 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?

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning: it groups the event types into inbound/outbound/batch and spells out the agent-key versus member-key scoping rule. The keyword-rule semantics (literal terms, any/all, exclusions) are summarized here with detail that complements rather than repeats 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?

It states a specific verb and resource ('Create a webhook') and immediately enumerates the configuration surface: name, public HTTPS URL, event types and keyword rules. An agent can see the intent and scope without opening the schema, and the mention of the one-time signing secret distinguishes it from the list/get webhook siblings.

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

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

It gives real operational conditions: requires explicit user intent for the URL, requires webhook.manage, agent keys must use their own agent_id and environment while member keys may pass null for account scope, and the idempotency_key must be reused after an uncertain mutation. It does not, however, name an alternative such as update_webhook_endpoint or rotate_webhook_endpoint_secret, so the agent must infer when to modify rather than create.

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, so the bar is lower, and the description adds genuinely useful behavior: volume discounts (5%/10%), the per-piece price floor, that minimums suppress discounts, and that sandbox keys return credits_required_cents 0. It stops short of describing latency or rate limits.

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 in one sentence, but the bulk is a dense pricing table that largely restates what the tool itself computes and returns — and an output schema exists, so return values need no narration here. Many exact price points and edge rules are not needed for tool selection, making it far longer than its selection job requires.

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 read-only annotations and an existing output schema, the definition is complete enough: it establishes what the number represents (exact debit amount), the batch size ceiling (10,000), sandbox behavior, and the minimum-price floor. It slightly over-delivers on return content but leaves no blocking gap for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds pricing meaning the schema does not: color adds 16¢ per color page, duplex is included (two pages per sheet), postcards are always full color, and mailing_class choice materially changes the price base. That is real added semantics over the 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?

Opens with a specific verb+resource+scope: 'Price a batch before any file exists.' That is clearly distinguishable from create_batch_mail and confirm_batch_mail, and the estimate/price framing separates it from quote_outbound_mail for one-off 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?

Establishes the pre-file timing, gives quantity thresholds (postcards from 1, letters/flyers/pamphlets from 10) and routes small orders to send_outbound_mail, plus links the estimate to confirm_batch_mail by saying it is 'the exact amount confirm debits.' It does not explicitly state when-not to use it beyond those thresholds, so it falls short of 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?

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 establish readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: the full status lifecycle, the 'first 50 pieces' truncation boundary, and webhook events that duplicate this data. It doesn't state what happens beyond 50 pieces (pagination or a separate call), which is the one gap.

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

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

The status-chain parenthetical is valuable but dense, and the sentence opens with the clipped fragment 'A batch with its status' rather than a verb-first statement of the action. Two sentences total with little waste, but the front-loading could be stronger.

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 spelled out, and the description still summarizes them usefully. Polling guidance and webhook alternatives cover the main operational question; only the post-50-pieces behavior is left unaddressed.

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

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

Schema description coverage is 100% and the single batch_id parameter is already documented in the schema as a UUID sourced from create_batch_mail or list_batch_mail. The description adds nothing about the parameter, 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?

It describes retrieving a single batch and enumerates what comes back (status, recipient summary, pricing, links, first 50 pieces), which is enough to tell it apart from list_batch_mail. It never uses an explicit verb like 'fetch' and relies on the schema's mention of create_batch_mail/list_batch_mail for framing, so it is clear but not razor-sharp.

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 an explicit trigger, and the mention of batch.submitted / batch.completed webhooks tells the agent when polling is unnecessary. It stops short of naming list_batch_mail as the alternative for enumerating batches, so the routing is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-schema behavior: the link expires in one hour, requires no API key, and is openable in any browser or IDE, plus it contrasts with the key-requiring API route.

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?

Single dense paragraph that front-loads the deliverable before the usage instructions, with no filler sentences. It is on the long side, but every clause (expiry, no key, sequencing, alternative) carries information.

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

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

With an output schema present, return values need no explanation, yet the description still summarizes them. Usage, sequencing, and the sibling alternative are all covered; only error/permission edge cases are absent, which is minor for a read-only proof fetch.

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 recipient are already fully documented with defaults and 1-based indexing. The description only implicitly touches the recipient parameter ('one recipient at its real size') and adds no format or syntax 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?

The description states a specific verb and resource ('a proof for the person checking the batch') and enumerates exactly what is produced: a one-hour PDF link of the template, the address label at real size beside the return address, plus the label lines as text. It is clearly distinguishable from siblings like 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?

It gives explicit sequencing ('Call it after create_batch_mail and give the person proof_url before confirm_batch_mail') and names the alternative route ('links.proof on the batch is the API route itself and needs the API key') with the condition that selects it. Nothing about when to use this tool 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 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds real substance: a hard 50-item bound with no paging, the tenant/agent/Live-Sandbox authorization model, the permission required, and the important caveat that HTTP 2xx means receipt rather than external-agent processing. Selection/redaction boundaries (no signing secrets, no receiver response body) are disclosed; only return ordering/pagination edge behavior is left implicit, which the output schema covers.

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 verb, resource, and result shape, then caveats, then auth and docs link — a sensible order with near-zero waste. The idempotency_key sentence is irrelevant to a read-only listing and slightly dilutes focus.

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 everything an agent needs to call this correctly: scope (one endpoint, latest 50 only), required permission and tenancy model, what data is and is not returned, and what a 2xx delivery does and does not imply. Return shape is also backed by an existing output schema.

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

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

Single parameter at 100% schema coverage already documents endpoint_id as a UUID sourced from list_webhook_endpoints, so the schema does the work. The description reinforces 'for one webhook' but adds no format or edge cases (e.g., unknown or deleted endpoint) beyond that.

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 and their exact JSON payloads ... for one webhook') and enumerates what the payload contains versus what it never contains (page text, secrets, receiver response body). This is clearly distinguishable from list_webhook_endpoints (endpoints) and replay_webhook_delivery (re-send).

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

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

Usage is implied by the scope ('for one webhook', 'latest 50', no paging) and by the webhook.manage auth requirement, but no sibling is named and there is no explicit when/when-not against list_webhook_endpoints, replay_webhook_delivery, or test_webhook_endpoint. The idempotency-reuse sentence reads as inherited boilerplate on a read-only tool and adds no routing guidance.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: returned data excludes secrets, webhook.manage is required, and the same tenant/agent/Live-Sandbox authorization model applies. The idempotency-key sentence is somewhat irrelevant for a zero-parameter read-only list, 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 core purpose is front-loaded and useful, but the sentence about reusing an idempotency_key after an uncertain mutation does not clearly apply to a read-only, parameterless list tool. That sentence feels like boilerplate and weakens an otherwise reasonably structured description.

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 enough for a zero-parameter list tool with an output schema and rich annotations. It covers permissions, secret exclusion, legacy separation, and authorization scope. Only minor ambiguity remains around pagination or result bounds, but that is largely covered by the output schema and annotations.

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

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

There are zero input parameters, so the baseline is 4. The description does not need to explain parameter semantics, and no parameter-level meaning is missing.

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: listing the member's webhooks, and enumerates the returned fields (name, URL, events, keyword rules, status). It also distinguishes this from legacy agent callback settings, though it does not explicitly differentiate from the sibling list_webhook_deliveries 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?

It gives useful context: requires webhook.manage and legacy agent callback settings are separate. However, it does not explicitly say when to use this tool versus alternatives such as list_webhook_deliveries, making the usage guidance implied rather than complete.

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 declare readOnly/idempotent/non-destructive, so the burden is lighter; the description nonetheless adds that no account is required, that nothing is created, and that the returned figure is the published price with a breakdown in USD. Returned-value detail goes beyond the annotations, though the meaning of the closing sentence about the "dry run of the real document" is somewhat opaque.

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

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

Front-loaded with the core purpose and four dense, mostly waste-free sentences. The final sentence ("The dry run of the real document is the exact price for an account") is grammatically muddy and costs clarity relative to its length.

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

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

An output schema exists so return values need not be explained, yet the description still characterizes the price output and breakdown. With annotations covering the safety profile and 100% schema coverage, an agent has everything needed 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 description coverage is 100%, so the schema already documents all four parameters including the FedEx ZIP dependency and defaults. The description restates the same inputs (mail class, page count, color, FedEx recipient ZIP) without adding format or constraint detail beyond the schema, which is the expected baseline 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 (price/quote) and resource (an outbound letter) and frames the timing constraint ("before you have the document"), which separates it from send_outbound_mail and get_outbound_mail. The phrase "creates nothing" further differentiates it from the create/send 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?

Gives clear when-to-use context (price before the document exists, dry run for an account) and prerequisites ("Needs no account"). It does not name sibling alternatives such as quote_inbound_forward or send_outbound_mail, so routing relies on inference rather than explicit comparison.

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?

Goes well beyond the destructive/idempotent hints: it discloses the 24-hour overlap window for old signatures, the required webhook.manage scope, the no-logging/no-prompt handling constraint, tenant and Live-Sandbox authorization scope, and the retry contract. That is exactly the context the annotations alone cannot convey.

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

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

Front-loads the authorization gate and confirmation flag in the first clause, then layers safety, permission, and retry details in short declarative sentences. Every sentence carries a distinct operational constraint with 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?

Covers permissions, reversibility window, side effects, and retry semantics, and links to docs; an output schema handles the return shape. The one gap is that it never says the new secret is surfaced only in the response, which is the most important handling detail for a rotation 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 every parameter is already documented in the schema. The description reinforces confirm_rotation:true and idempotency_key reuse, but those points duplicate the schema text, and expected_revision is not discussed at all.

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 ('Rotate the signing secret') and makes clear it is the secret-rotation operation, not the general endpoint edit or test operations performed by update_webhook_endpoint or test_webhook_endpoint. An agent can select it 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?

Sets a clear precondition ('only with explicit operator authorization') and a retry rule ('reuse the exact idempotency_key and input after an uncertain mutation'), plus the follow-up action of updating the receiver's configuration. It never names a sibling alternative (e.g., that update_webhook_endpoint handles non-secret changes), so routing guidance is implied rather than explicit.

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