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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, with mail_id already documented as 'UUID of the test_mode outbound mail record to advance.' The description reinforces the same conceptual framing and adds lifecycle context, but it does not add new parameter-level details or syntax, so the baseline score of 3 applies.

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

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

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

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

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

The description clearly scopes the tool to test_mode records and defines the state-transition behavior, so an agent can infer when it should be used rather than creation or cancellation tools. It does not explicitly name alternatives or say 'do not use for production mail,' but the test_mode qualifier and sibling names provide adequate directional guidance.

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

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

The description substantially exceeds the annotations. While annotations already note idempotentHint=true and destructiveHint=true, the description explains the specific destructive side effect (returning prepaid credits), confirms idempotency ('already-cancelled mail returns cancelled status without creating a duplicate refund'), and adds operational guidance (chat reporting requirements and error polling). This provides context far beyond the boolean hints.

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

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

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

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

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

For a tool with one parameter and an output schema, the description is exceptionally complete. It covers the action, timing constraint, side effects, retry behavior, what to report in chat, and how to handle transient errors. There are no significant gaps that would prevent an agent from using the tool correctly.

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

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

The input schema fully describes mail_id as 'UUID of the queued outbound mail job to cancel' with 100% coverage. The description does not add additional meaning to the parameter itself, so the baseline of 3 is appropriate. No extra semantics are needed for a single, well-documented parameter.

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

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

The description clearly states the action: 'Cancel a queued outbound mail job before facility printing starts.' This specifies the verb 'cancel', the resource 'outbound mail job', and a critical condition ('before facility printing starts'). It distinguishes the tool from siblings like send_outbound_mail (which creates) and get_outbound_mail/list_outbound_mail (which read), by focusing on cancellation of a queued job.

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

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

The description provides clear context for usage: it is for cancelling queued mail before printing begins, and it includes retry guidance ('Safe to retry') and error handling ('poll the mail status and credits before retrying'). It lacks an explicit comparison to alternatives, but the condition 'before facility printing starts' and the action 'cancel' make when to use it unambiguous given the sibling set.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations cover the safety profile (non-readOnly, non-destructive, idempotent, open-world). The description adds value beyond them: the whsec_ signing secret is returned exactly once and must never be logged or mailed, the endpoint is active on save, and permission/tenant/agent/Live-Sandbox authorization is spelled out. This is exactly the kind of 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?

Dense but front-loaded: purpose first, then secret-handling warning, then authorization, then retry guidance, then docs link. The event list is duplicated between the description and the schema's event_types, which is a small waste, but every other clause 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?

An output schema exists, so return values need not be explained, yet the description still flags the one-time whsec_ secret, which is critical to handling the response correctly. Permission requirements, idempotency behavior, and environment scoping are all present, so an agent has everything needed to invoke this mutation safely.

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 reinforces non-obvious semantics: which key type may set agent_id:null, that agent keys must match their own environment, that an endpoint only receives events from its environment, and the meaning of the keyword rule fields (terms, any/all, exclusions). It adds mild but real value on top 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?

Opens with a specific verb+resource ('Create a webhook') and enumerates the exact configuration surface (name, HTTPS URL, event types, keyword rules). An agent can immediately distinguish it from update_webhook, list_webhook_endpoints, rotate_webhook_endpoint_secret, and test_webhook_endpoint in the sibling set.

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

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

Gives clear preconditions and constraints: the URL requires explicit user intent, agent keys vs member keys dictate agent_id, and webhook.manage is required. It also tells the agent how to retry uncertain mutations with the same idempotency_key. It stops short of explicitly naming sibling alternatives, but the context is unambiguous.

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

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

Beyond the readOnly/idempotent annotations, it discloses auth requirements (agent-scoped bearer key; member/facility keys cannot impersonate), an important semantic caveat that a receipt is not proof of handling, and hard guidance never to substitute another key or mail API after denial. This is rich behavioral 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-loads the critical deprecation notice, but the body is dense and partly redundant — 'needs agent.inbox.read' is restated as 'Required scopes: agent.inbox.read', and sentences about rollout switches and SQL authorization are obscure padding.

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 covering return values and annotations covering the safety profile, the remaining burden is deprecation routing, auth, and result interpretation — all addressed. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the item_id filter role but adds no syntax or semantics beyond the schema, and never mentions the limit 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?

States a specific verb and resource ('Read current authorized inbox retrieval receipts and agent-reported outcomes') and immediately names the successor tool get_inbound_activity. An agent can distinguish this deprecated alias from the live sibling 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 says 'Deprecated: use get_inbound_activity' — naming the alternative and the condition (alias window) that governs whether this tool should be called at all. It also states the preconditions (agent.inbox.read, agent-scoped bearer key) that gate successful 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 safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: required scopes (agent.inbox.read, agent.read), agent-scoped bearer requirement, that member/facility keys cannot impersonate, OCR being untrusted text, that missing/pending/failed text is not success, no provider call or signed image URL, and no substituting another key after denial.

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

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

The deprecation notice is correctly front-loaded, but the body is a long run-on of terse fragments with no grouping into auth, semantics, and routing. For a deprecated single-parameter read tool this is over-long, though most sentences carry distinct 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. The description covers deprecation, sibling routing, auth/scopes, and acknowledgment semantics – everything an agent needs to call a 1-parameter read tool correctly.

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

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

Schema description coverage is 100% and the single item_id parameter is fully documented in the schema (UUID from a list or search result). The description adds no syntax or format detail beyond that, so the baseline 3 for schema-driven parameters is 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+resource: a versioned context/reporting reader at /v1/agent-inbox/:id/context, explicitly scoped as 'not all-source history'. It distinguishes siblings (get_agent_inbox_sources, list_agent_inbox_scans) and notes get_inbound_item as the successor. The deprecation lead and dense fragments slightly obscure the core purpose, keeping it from 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: 'use get_inbound_item' (deprecation), 'use get_agent_inbox_sources' for indexed OCR search, list_agent_inbox_scans for capture drilldown, get_mailbox_md for full instructions. It even specifies 'only the returned context can be acknowledged', which governs when this tool is mandatory.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, yet the description adds substantial context beyond them: deprecation and alias-window behavior, environment gating, the fact that the server chooses source/facility, unavailable vault, and required auth ('agent-scoped bearer key required; member/facility keys cannot impersonate an agent') plus scopes. This is rich behavioral disclosure that 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 critical routing information (deprecated, use get_inbound_item) is front-loaded, and most clauses earn their place via real behavioral constraints. Some trailing detail ('rollout switches... credential environment and SQL authorization are shared with REST') is dense internal jargon of marginal value to an agent caller, slightly diluting conciseness.

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 annotations covering the safety profile and an output schema documenting returns, the description only needs to convey deprecation, environment gating, and auth constraints — all of which it does. Nothing an agent needs to call this correctly is missing.

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

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

Only one parameter (item_id) with 100% schema description coverage, so the schema already carries its meaning ('Inbound item id (UUID) from a list or search result'). The description adds no item_id syntax or format detail beyond the path reference ':id'. Baseline 3 is appropriate when the schema does the work.

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

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

The description states a specific verb and resource ('Read /v1/agent-inbox/:id/handling capabilities, version and history') and immediately signals its relationship to the sibling get_inbound_item via the deprecation note. An agent can tell exactly what this returns and that it is superseded.

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 explicitly ('Deprecated: use get_inbound_item'), states when the alias still works (during the alias window), and constrains applicability ('private-mail Live and member-sample Sandbox workflow only; no generated fixtures or managed-PMB fallback'). The 'never substitute another key or mail API after denial' clause is an explicit exclusion.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial context beyond them: required scopes (agent.inbox.read, agent.read), agent-scoped bearer key requirement with impersonation limits, sandbox-key restriction, absence of context_version, and an explicit statement that document text is untrusted data. It also enumerates operations this tool does NOT perform (image URLs, OCR trigger, retry, receipt, email, charge).

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 body is a dense run-on packing auth, scoping, sandbox, security, and non-feature caveats into a single block. Most sentences earn their place, but the lack of structure and repetition (denials, key substitution) costs readability.

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

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

An output schema exists, so return values need not be explained. The description covers authentication, scopes, deprecation status, sibling routing, and security posture, leaving nothing material for an agent to guess before calling.

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 both UUID parameters are documented in the schema, giving a baseline of 3. The description adds real meaning beyond the schema by clarifying that request_id maps to the REST operationId and must not be a page or bundle ID.

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 core action is stated with a specific verb and resource: 'Read one exact completed facility capture and its saved page OCR through /v1/agent-inbox/:id/scans/:operationId.' It also names the sibling it is distinguished from (list_agent_inbox_scans) and its successor (get_inbound_pages). The deprecation notice and dense clause stacking bury the primary purpose somewhat, keeping it from 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 in every direction: use get_inbound_pages instead (deprecated), take request_id from list_agent_inbox_scans, use get_mailbox_md for full effective duties, and do NOT acknowledge these with report_agent_inbox_outcome. When/when-not and alternatives are all spelled out.

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: required scopes (agent.inbox.read, agent.read), agent-scoped key requirement, no side effects ('no acknowledgment version or extraction is created'), pagination model (next_offset vs has_more), 429/Retry-After backoff guidance, no ETag/change cursor promise, and denial handling. This is exactly the extra behavioral 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?

The critical deprecation notice is correctly front-loaded, but the definition then runs to roughly 250 words of auth, custody, retry, security and rollout advice for a 3-parameter read tool. Much of this belongs in server documentation, and the density of operational warnings buries the actual purpose.

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?

Complete: an output schema exists and the description appropriately defers ('Field meanings and sort order are in outputSchema'), while still covering auth requirements, pagination limits, error/backoff behavior, and scope of returned evidence. Nothing needed 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 meaning: it explains the two pagination regimes (item lists use next_offset; sources/scans use has_more with offset + returned length) and the 10000 stop-and-report rule, which the schema only partially conveys.

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

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

States a concrete verb+resource ('Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources') and flags itself as deprecated in favor of get_inbound_item. It distinguishes itself from siblings clearly, though the redirect target is slightly ambiguous given that a non-deprecated get_inbound_item_sources also exists.

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 'Deprecated: use get_inbound_item. Still served unchanged during the alias window,' naming the alternative and the migration condition. It also advises narrow queries/date windows and fetching selected items rather than every mailbox, though it never states a positive when-to-use case beyond legacy migration.

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?

Goes well beyond the annotations: it warns a row proves recording only, 'not OCR accuracy or physical completion'; clarifies that proposals are agent-only and never charge credits, buy postage, open, forward, or discard on their own; notes policy-checking of forward/discard proposals; states image URLs are never issued to agents; and instructs to stop on denial without switching keys/APIs. This is rich behavioral disclosure an agent cannot infer from 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?

Purpose is front-loaded and sentences are dense but largely purposeful, covering scope, semantics, and safety. It is longer than strictly necessary, with some enforcement-style guidance ('never switch keys or mail APIs to bypass it') that borders on policy lecturing rather than tool usage, keeping it from a 5.

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

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

For a read-only timeline tool with an output schema (so return values need not be explained), the description fully covers scope, ordering, pagination intent, key-based visibility, and the proposal/policy caveats. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100%, so limit/offset/item_id are already fully documented (including pagination semantics). The description adds only marginal value, restating that item_id narrows to one item, with no additional syntax, constraints, or interaction detail. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb and resource ('Read the inbound timeline through GET /v1/inbound-activity') and enumerates the returned event types (received, action proposed/requested/started/completed/rejected) and ordering (newest first). This event-timeline scope is clearly distinct from the item-listing and single-item siblings (list_inbound_items, get_inbound_item).

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

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

Provides clear context for narrowing ('Optional item_id narrows to one item') and for key scope (member keys read their own live items; agent keys read bound/assigned items). It does not, however, explicitly name an alternative tool or state when-not-to-use this versus a sibling, so it falls short of the 5-level 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious context: OCR text is untrusted document data, signed_urls behaves differently on live vs sandbox keys, proposals are agent-only and never spend credits or open/forward/discard, forward/discard proposals are validated against the agent's policy, and image URLs are never issued to agents.

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 the first clause, and the dense subsequent sentences each carry distinct information (untrusted text, key scope, proposal policy, image URL rules). It is long, but the length is justified by safety/policy content rather than padding.

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

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

An output schema exists, so return values need no prose explanation, and the description still covers everything an agent needs to call it correctly: id source, key scopes, permissions, sandbox behavior, and denial handling. Nothing material is missing for a two-parameter read that already has structured output.

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 both parameters (baseline 3). The description goes slightly beyond it by reinforcing the live-vs-sandbox signed_urls behavior and adding the constraint that image URLs are never issued to agents, but it adds no new syntax for item_id beyond the schema's UUID note.

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

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

The description opens with a specific verb+resource and endpoint ('Read one inbound item through GET /v1/inbound-items/:id') and then enumerates exactly what the read yields: canonical status, sender, PMB, assigned agent, pages with OCR status/text, action history, and quotes. This contrasts cleanly with list/search siblings, and it explicitly points to search_inbound_items as the id source.

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 tells the agent where item ids come from ('Use item ids from search_inbound_items') and states key-scope/permission rules (member vs agent keys, environment) plus a stop-on-denial rule. It gives clear context for correct invocation but never explicitly contrasts single-item reads against adjacent siblings like get_inbound_pages or get_inbound_mail.

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

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

Annotations already cover read-only/idempotent/closed-world safety, but the description adds far more: it does not require an active eligible managed mailbox that must be saved-document-reads enabled, both inbound.item.read and inbound.item.scan.read scopes even for empty searches, key-scoping rules for live member vs agent keys, absence of facility/Sandbox/package.read compatibility, denial-handling, non-snapshot-consistency, and Retry-After/concurrency/backoff guidance.

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 correct, but the remainder is a dense, unbroken run-on mixing auth, pagination, concurrency and scope caveats with no visual separation. Most sentences carry information, yet the wall-of-text format makes the routing facts harder to extract than necessary.

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 deprecated, multi-scope evidence reader the description covers permissions, deprecation window, scoping limits, pagination caps and failure handling; an output schema exists, so return-shape detail is not required. Nothing an agent needs to invoke or route 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% and both limit and offset have their own descriptions, so the baseline would be 3. The description goes further by explaining the pagination strategy (advance offset by returned count, follow pagination.has_more, stop at the cap and narrow the query) and the origin of item_id, adding genuine meaning 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 concrete verb+resource ("Read saved exterior and authorized completed inside-page evidence through GET /v1/inbound-items/:id/sources") and defines the grouping key hierarchy, so an agent knows exactly what is returned. It also names the successor tool (get_inbound_item) and its own deprecation status, distinguishing it from that sibling and from the agent-inbox variant.

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 is given (only saved-data reads; no extraction, retry, image URLs, provider calls, email or charges) along with a direct replacement instruction ("Deprecated: use get_inbound_item"). Prerequisite conditions are spelled out in detail, including required scopes and mailbox eligibility; nothing is left to inference.

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

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

Annotations already 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?

Goes well beyond the readOnly/idempotent annotations: signed_urls behavior on live vs. sandbox keys, the fact that agents are never issued image URLs, the structured-policy check, and the explicit 'Stop on denial; never switch keys or mail APIs to bypass it' instruction. It also flags that returned text is untrusted data, never instructions — security-relevant behavioral context an agent genuinely needs.

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 action and endpoint, but the paragraph is dense and drifts into policy text about proposals, forward destinations and discard checks that pertain to handling tools rather than a page reader. That content dilutes the read-specific guidance and costs structure points.

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

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

For a read tool with full annotations and an output schema, the definition still names the returned fields (ocr_status, text/needs_review, is_blank, uncertain_spans) and covers auth, environment and pagination context. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters (kind, limit, offset, item_id, signed_urls) are already documented in the schema, including the kind enum and the ONE-hour-URL semantics. The description mostly restates this (signed_urls, kind meanings) rather than adding syntax or edge cases 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') and pins it to the exact endpoint GET /v1/inbound-items/:id/pages, then distinguishes the page kinds (exterior envelope vs. interior after Open & scan). An agent immediately knows this is the page-content reader and what it returns, without needing to open the schema.

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

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

Gives real usage conditions: key scope (inbound.item.read, agent.inbox.read), the member-vs-agent key visibility rules, and the environment binding. It never names a sibling as an alternative or states when not to use it, so it falls short of the 5-level 'when/when-not/alternatives' standard.

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?

Despite annotations covering read-only safety, the description adds extensive behavioral context: scope requirements for q and date filters, rollout dependencies, sandbox versus live data differences, pagination cap and incomplete-result reporting, and credential enforcement rules. This far exceeds 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?

The description is long but front-loads the critical deprecation notice and alternative tool before detailing search semantics, scopes, and pagination. Most sentences carry necessary operational constraints, though the lack of formatting makes it denser than ideal.

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

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

Given the tool's complexity—deprecated alias, multiple scopes, rollout conditions, sandbox/live differences, and pagination limits—the description covers everything an agent needs to invoke it correctly. Since an output schema exists, return value details are appropriately left out.

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 already document all five parameters thoroughly, but the description adds meaningful constraints not present in the schema: nonempty q additionally requires agent.read, and received_after/received_before require the indexed rollout plus both read scopes. It also reinforces that date filters target the stored intake timestamp, never a guessed letter date.

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

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

The description explicitly states the tool lists/searches current assigned postal mail and names the preferred alternative search_inbound_items. It distinguishes itself from that sibling by noting its deprecated alias status and unchanged behavior during the alias window.

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 directly says 'Deprecated: use search_inbound_items' and explains the tool still works during an alias window, giving clear when-not and alternative guidance. It also directs users to get_agent_inbox_sources for reading selected matches and warns against substituting another key or mail API 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?

Goes well beyond the readOnly/idempotent annotations: discloses pagination mechanics and the 10000 offset cap, the 'current view, not a snapshot' caveat, that completion is not extraction success, the OCR status enum meaning, that no provider/retry/acknowledgment is triggered, and the required scopes and key restrictions. This is rich behavioral context an agent cannot infer from 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?

Front-loads the critical deprecation notice first and every clause carries information, but the remaining single dense block packs auth, pagination, OCR and rollout caveats into run-on sentences, raising reading cost.

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 deprecated, auth-heavy, paginated list tool it covers the scopes, key constraints, pagination limits, OCR semantics, and rollout caveats. An output schema exists so return values need no further explanation, and the description is complete without it.

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 q, limit, offset and item_id are already fully documented. The description restates q's literal AND/NFKC behavior and the offset cap, adding little 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 ('List/search completed facility-captured scan jobs') scoped to 'this assigned member sample' via an explicit endpoint path. It also names its replacement (get_inbound_pages) and distinguishes itself from the seeded sample /context, so an agent can separate it from siblings without opening schemas.

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

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

Explicit when-to-use routing: 'Deprecated: use get_inbound_pages' plus the alias-window caveat, and how it differs from the seeded sample /context endpoint. It also states the precondition (sandbox agent key only, required scopes) that selects or excludes this 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, 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 establish a safe read-only, idempotent profile, but the description adds substantial context beyond them: exact auth requirements (saved-document reads enabled, eligible managed mailbox, both inbound.item.read and inbound.item.scan.read), member vs agent key scoping, no facility/Sandbox/package.read compatibility, non-snapshot results, Retry-After/backoff expectations, and a clear statement that no extraction/retry/signed URL/provider call occurs.

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 and purpose are correctly front-loaded, but the body is ~250+ words of dense prose with several negative-clause disclaimers that repeat the same 'reads only' idea and a trailing aside about member keys vs agent duties (get_mailbox_md) only loosely related to this call. Most sentences carry operational value, but the sheer density and mild redundancy hurt scanability.

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

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

Given the tool's complexity — deprecation, dual read scopes, key-scoping rules, pagination caps, non-snapshot results — the description covers everything needed to call it correctly. An output schema exists, so return-value detail is appropriately left to it while the description still warns that only metadata/identity, not page text, comes back.

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 every parameter; the description nonetheless adds real meaning on top — that q is literal AND across NFKC/lowercased metadata and OCR, that terms may match different pages of one item, that received_after is inclusive while received_before is exclusive and both filter intake time not printed dates, and that sender/address terms must go through q.

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 concrete verb and resource ('Search managed-renter physical mail') and even pins the underlying endpoint and search mode. It explicitly distinguishes itself from its sibling search_inbound_items by declaring the deprecation/alias relationship, so an agent knows exactly which version it is calling.

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 when-not-to-use guidance ('Deprecated: use search_inbound_items'), a named alternative for follow-up detail (get_inbound_item_sources for selected items), and stop conditions (stop at offset cap; never switch keys/accounts to bypass denial). Routing decisions are fully covered rather than implied.

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?

Beyond the annotations, the description discloses many operational traits: only the latest 50 deliveries, exact payload fields included and excluded, no signing secrets or receiver response body, and that HTTP 2xx means receipt rather than external-agent processing. It also states the required permission and authorization 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 key scope is front-loaded and the description is dense with useful constraints. However, the sentence about reusing an idempotency_key after an uncertain mutation is irrelevant to this read-only listing tool and slightly harms 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?

The description covers return content, exclusions, limits, permissions, and authorization context, which is strong for a one-parameter tool with an output schema. The stray idempotency_key guidance is not applicable and prevents a perfect score.

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 sole endpoint_id parameter is already fully documented. The description adds no additional parameter semantics and mentions an idempotency_key that is not actually an input parameter, which is potentially misleading.

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 specific verb and resource: read the latest 50 deliveries and their exact JSON payloads for one webhook. It also scopes what is included and excluded (identifiers, sender line, dates, matched terms; never page text), making it clearly distinguishable from endpoint-listing or replay tools.

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

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

It establishes clear context: read deliveries for one webhook, requires webhook.manage, and shares the authorization model of the webhooks endpoints API. It does not explicitly name alternatives such as replay_webhook_delivery or list_webhook_endpoints, and the idempotency_key sentence is confusing for a read-only 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 cover readOnly, idempotent, non-destructive, and closed-world behavior; the description goes beyond them by disclosing the required permission (webhook.manage), the authorization scope (tenant/agent/Live-Sandbox), and that secrets are not returned. It also clarifies that legacy agent callback settings are out of scope, adding meaningful behavioral context without contradicting annotations.

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

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

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

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

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

For a zero-parameter, read-only tool with a rich output schema and annotations, the description is nearly complete: it covers scope, permission, authorization boundaries, exclusions, and provides a documentation link. The irrelevant idempotency note is a minor clarity issue but does not leave an agent without the information needed to call the tool correctly.

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

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

The tool has zero parameters and the input schema is complete, so there is nothing for the description to add about individual parameters; the baseline-4 rule applies. The description does add value by specifying what the returned webhook data includes and excludes, which helps an agent interpret the output.

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

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

The description opens with a specific verb and resource—'List the member's webhooks'—and enumerates the returned fields (name, URL, events, keyword rules, status) while excluding secrets. It also notes that legacy agent callback settings are separate, but it does not explicitly name sibling tools like list_webhook_deliveries or create/update endpoints, so the sibling differentiation is partial.

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

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

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

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses the human-approval gate, that the caller cannot self-approve/dispatch/charge/destroy, required scopes, key-impersonation rules, and idempotent replay semantics ('same key with the same input replays the stored result'). This is unusually rich behavioral context for a mutation tool.

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 routing is correctly front-loaded, but the body is a dense semicolon-chained wall that repeats scope info ('dedicated agent.inbox.propose and read scopes' then 'Required scopes: ...'). Information-dense but weakly scannable, with some 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 annotations, a full input schema, and an output schema already present, the description fills the remaining gaps: deprecation status, successor tool, auth/scopes, approval flow, version-read prerequisite, and idempotency/retry rules. An agent has everything needed to invoke it correctly despite the alias.

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 dictates confirmed:false / destructive_confirmed:false values, explains forward vs. discard requirements, clarifies the expected_version/idempotency_key retry contract, and flags that sample open_and_scan is TEST-only. It omits per-field detail on item_id, which the schema already covers.

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 specific verb+resource ('Propose through /v1/agent-inbox/:id/handling') and explicitly names the sibling that supersedes it (request_inbound_action), so an agent can distinguish it from the rest of the inbox family. The core action is slightly obliquely expressed by leading with the deprecation notice rather than the function, which keeps it just under 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?

It states the decisive condition ('Deprecated: use request_inbound_action' during the alias window), prerequisites ('Read capabilities/version first', agent-scoped bearer key required), and post-denial behavior ('Never substitute another key or mail API after denial'). Alternative routing plus edge-case guidance is fully explicit.

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?

With annotations already declaring read-only, idempotent, non-destructive behavior, the description adds substantial context: cost formula, handling breakdown, tracking notes, bill timing, sample versus live pricing, scope requirements, key-environment behavior, proposal limits, policy checks, and image URL restrictions. It contradicts none of the annotations and meaningfully extends them.

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

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

The purpose and workflow are front-loaded, and most sentences carry operational or safety information. The description is dense and somewhat run-on, but it avoids repetition and keeps essential details rather than padding.

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

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

For a read-only quoting tool with a rich output schema, the description covers the call, the downstream action, scope/auth constraints, sample behavior, policy checks, and safety boundaries. An agent has enough context to invoke it correctly without needing return-value documentation.

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 two parameters are already fully documented in the input schema. The description reinforces that item_id is an inbound item and postal_code is a destination ZIP, but it adds no syntax or format detail beyond the schema baseline.

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: pricing every forwarding class for an item to a US ZIP. It also names the API path and the downstream consumer tool, request_inbound_action, so an agent can distinguish this quoting operation from sibling read/write tools.

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

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

The description explicitly says to choose a class and pass the quote as action.expected_quote to request_inbound_action. It also gives the sample/test item exception and identifies the required scope, key behavior, and stop-on-denial rule, leaving little ambiguity about when and how 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?

Adds substantial behavior beyond the annotations: event_id deduplication, rechecking the current endpoint revision, required webhook.manage scope, tenant/agent/Live-Sandbox authorization, and the bounded control plane. Annotations cover the safety profile, and the description layers on auth, concurrency, and dedup semantics.

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 retry action and precondition are front-loaded, and each sentence carries distinct information (boundaries, auth, idempotency, docs). It is denser and longer than strictly minimal, but no sentence is 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 and annotations covering the safety profile, the description supplies everything else an agent needs: authorization scope, concurrency protection via revisions, dedup behavior, exclusions, and a docs link. Nothing material 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 meaning beyond the schema's per-field text: idempotency_key reuse after an uncertain mutation and the revision recheck semantics tied to expected_revision. These are operational nuances the schema alone does not convey.

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 webhook delivery) plus its precondition ('after correcting the receiver') and an explicit boundary ('Does not replay successful deliveries'). An agent can distinguish it from list_webhook_deliveries or test_webhook_endpoint 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?

Gives clear when-to-use ('after correcting the receiver') and when-not ('Does not replay successful deliveries') guidance, plus an idempotency retry condition for uncertain mutations. It stops short of naming the alternative sibling to use for other cases, so it is clear context without explicit 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?

Goes well beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing deprecation/no-successor status, required scopes (agent.inbox.read, agent.read, agent.inbox.report), the agent-scoped bearer key requirement, the member/facility impersonation restriction, idempotency replay semantics, and shared rollout/authorization dependencies. This is exactly the extra behavioral 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?

Information is dense and mostly front-loaded with the deprecation warning, but it is a run-on series of sentences with redundancy: the scope set is stated twice ('agent.inbox.report plus both read scopes' then 'Required scopes: agent.inbox.read, agent.read, agent.inbox.report'), and retry/denial warnings are repeated. It could be tightened without losing 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?

For a deprecated mutation tool with an output schema present, the description supplies everything an agent needs: lifetime status, endpoint, auth/scope requirements, idempotency and retry behavior, and clear constraints on what the report can and cannot do. Nothing essential is left implicit.

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 meaning: context_version must be the 'exact fetched' value and run_id should be 'non-sensitive', which clarifies correct usage beyond the field patterns. The nested request object is adequately explained via the description and schema together.

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: 'Report actual external-worker processing through /v1/agent-inbox/:id/acknowledgments.' An agent can distinguish this outcome-reporting tool from siblings like get_agent_inbox_context or propose_agent_inbox_handling. The purpose is somewhat buried behind the leading deprecation sentence but is unambiguous once reached.

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

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

Gives clear conditions: 'Retry only the same idempotency_key and request', 'Never report processed before doing the work', 'reports cannot approve or complete facility handling', and 'Never substitute another key or mail API after denial.' These are explicit when/when-not rules, though it never names an alternative sibling for reporting, so it stops short of full 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?

Goes well beyond the annotations (readOnly=false, destructive=false, idempotent=true) by disclosing that the proposal always waits for owner approval (awaiting_member_approval: true), never charges credits or moves mail, is limited to one open action per item, is checked server-side against inbound_policy, and returns no image URLs to agents. The idempotency_key retry semantics add concrete behavioral context.

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

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

Front-loaded and dense with useful information, but it repeats itself: the 'never charges credits / never moves mail' point appears twice and the 'forward destinations and discard proposals checked against inbound_policy' sentence appears verbatim twice. These duplicate sentences cost it conciseness.

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 covers the remaining burden for a mutation tool: key scope, approval gating, policy checks, idempotency, and per-action requirements. Nothing needed 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 description coverage is already 100%, so the baseline is 3, but the description adds real meaning: where expected_quote comes from, that expected_version must be the current version, and why idempotency_key exists for replays. It stops short of detailing the nested action variants fully, which the schema handles.

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 resource (scan/forward/discard on an inbound item) and even names the endpoint POST /v1/inbound-items/:id/actions. An agent can immediately tell this apart from get_inbound_item or quote_inbound_forward, which are referenced as supporting reads rather than competitors.

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 about prerequisites and conditions: agent keys only, expected_version from the item's current version, expected_quote sourced from get_inbound_item quotes.scan or quote_inbound_forward (required for scan/forward, refused otherwise), first_class requiring untracked_acknowledged: true, and packages not forwardable yet. It also names the stop condition (stop on denial, never switch keys).

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

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

Adds substantial context beyond the annotations: the 24-hour signature overlap window, the required permission scope, the instruction to update the receiver's secret configuration, and the secret-handling prohibition. The destructive/openWorld/idempotent hints are corroborated rather than merely restated.

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 action and its gate in the first sentence, then layers prerequisites, overlap behavior, and idempotency guidance. Slightly dense and contains a redundant restatement of the schema's const:true, but every sentence carries useful 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?

For a destructive, authorization-gated rotation with a full output schema, the description covers the safety profile, permission requirement, blast radius (24-hour overlap), and retry semantics. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds operational meaning by tying confirm_rotation to explicit operator authorization and clarifying that idempotency_key is a single-intent retry token, which the schema phrasing only partly conveys.

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') with an added scope/gating constraint, which separates it cleanly from siblings like update_webhook_endpoint, test_webhook_endpoint, and list_webhook_endpoints.

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 preconditions (operator authorization, confirm_rotation:true, webhook.manage scope) and post-incident guidance (reuse the exact idempotency_key after an uncertain mutation). It does not name an alternative tool for the non-rotation case, so it stops short of full when/when-not routing.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses key-scope semantics (inbound.item.read / agent.inbox.read, member vs agent visibility and environment binding), agent-only proposal behavior that never spends credits or performs side effects, policy checks on forwarding/discard, that image URLs are never issued to agents, and that empty results carry an explanatory notice. That is substantial behavioral context the annotations do not 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?

Purpose and result shape are front-loaded, then search semantics, sandbox behavior, and key scope follow in a logical order. It is dense and runs long for a search tool, and the proposal/image-URL sentences sit at the edge of this tool's remit, but nearly every clause carries operative 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-value explanation is not needed, and the description still covers the dimensions an agent needs: result ordering, filter semantics, pagination caveat (via schema), key scopes, environment constraints, sandbox seeding behavior, and how to proceed with returned item.id. 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 description coverage is 100%, so each parameter is already documented (q's AND semantics and 12-term/200-char limit, offset advance guidance, intake-time meaning). The description restates the search target ('reference, the sender and the OCR text of every readable page, envelope or contents') and framing of narrowing filters but adds little 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?

The first sentence states a specific verb+resource ('List and search inbound mail'), names the backing endpoint, and anchors it to a familiar surface ('the same list and search the dashboard shows'). It also enumerates what is returned (status, kind, sender line, envelope pages, open action), so an agent knows exactly what this call yields.

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 explains when each filter applies (q for literal AND search, status/kind/received_after/before to narrow) and gives concrete sandbox guidance ('start with q: "Mojave"') plus a stop condition ('Stop on denial; never switch keys or mail APIs to bypass it'). It does not explicitly name list_inbound_items or get_inbound_item as the alternative for a plain unfiltered listing, so it stops short of full when-not/alternative routing.

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

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

Goes well beyond the annotations by disclosing deprecation/retirement timing, that the fixture is isolated, provider-free and involves no real mail, model call, email, facility task, PMB or charge, plus the auth model (agent-scoped bearer required). It also explains idempotent replay semantics and behavior shared with REST. This is rich behavioral context the structured fields do not 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?

Deprecation and endpoint are front-loaded, and nearly every clause carries actionable information. It is dense and slightly repetitive ('Sandbox agent key only' vs 'Agent-scoped bearer key required'), which costs a point but does not obscure the core intent.

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; annotations cover the safety profile. Combined with the description's coverage of deprecation, auth, scope, idempotency and isolation, 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 both parameters, including the enum and idempotency replay rule. The description largely restates the enum values and the same-key-same-scenario reuse behavior rather than adding syntax or format detail. Baseline 3 applies 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 ('seed'), resource ('fixture'), the exact fixtures named (two_page_letter or needs_review), and the endpoint path (/v1/agent-inbox/sandbox/seed). It also front-loads the deprecation status, which no sibling exposes. An agent can distinguish this from read/report siblings like get_agent_inbox_scan 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?

Gives clear when-to-use constraints: sandbox agent key only, required scope agent.inbox.read, and member/facility keys cannot be substituted. It also rules out post-denial workarounds ('never substitute another key or mail API'). It does not name an alternative tool for seeding, but it explicitly states there is no successor, which closes that loop honestly.

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

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

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

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

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

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

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

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

An output schema exists, so return values need not be explained. The description supplies the audience/visibility and routing behavior needed to call this correctly; only explicit alternative-tool routing and delivery expectations are absent, which is a minor gap for a straightforward send tool.

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

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

Schema description coverage is 100%, so all three parameters (body length range, package_id, action_request_id) are already documented. The description only restates the optional linking behavior, adding no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond annotations, it discloses the required permission (webhook.manage), the authorization model (tenant/agent/Live-Sandbox, same as the REST endpoint), and the critical async caveat that queue admission is not HTTP delivery. It also states the uncertain-mutation retry rule for idempotency_key, which is exactly the behavioral context an agent needs for a mutating, idempotent tool.

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 dense but front-loads the core action and caveats first, then auth, then idempotency, then the docs link. Every sentence carries information, though the phrasing is compact enough that it reads more like a bulwark of constraints than a clean flow.

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: what it does, the async boundary, permissions, authorization scope, and retry semantics. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the idempotency_key retry semantics and expected_revision concurrency rationale. The description's idempotency guidance is largely redundant with 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?

It names a specific verb and resource ('Queue a synthetic webhook.test delivery') and scopes it ('no item'), which distinguishes it from the sibling test_webhook_endpoint_with_sample. It also explicitly contrasts the action with the sibling list_webhook_deliveries, so an agent can tell the tools apart without opening schemas.

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

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

It clearly states the use case (check the receiver and its signature verification) and routes the agent to list_webhook_deliveries for actual HTTP delivery status, which is an explicit alternative. The implicit contrast with test_webhook_endpoint_with_sample ('no item') is useful but not spelled out by name, so it falls just short of fully explicit 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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds substantial behavioral context: it is free, fictional, opens/scans a sample letter, delivers real events, proves only transport receipt and keyword match (never agent processing), requires webhook.manage, uses bounded control plane and tenant/agent/Live-Sandbox authorization, and specifies idempotency key reuse. This far exceeds the annotation coverage.

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

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

The description is front-loaded with the core action and keeps every sentence relevant: scope, limits, permissions, idempotency, and docs link. It is dense but not redundant; a slightly leaner phrasing could still convey the same information, but the length is justified by the tool's complexity.

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

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

Given the tool's complexity (a test that mutates webhook delivery state), the presence of annotations, and an output schema, the description is complete. It covers what the tool does, what it does not do, auth requirements, idempotency behavior, and how to interpret success, leaving no critical gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a meaningful nuance beyond the schema's idempotency_key description by specifying 'Reuse the exact idempotency_key and input after an uncertain mutation,' clarifying when reuse is appropriate. It also ties expected_revision to concurrent-edit safety, though that is largely echoed 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 states a specific verb and resource ('Run the Sample test' on a webhook endpoint) and distinguishes itself from the generic sibling test_webhook_endpoint by naming the 'Sample' test and describing the exact events delivered (inbound.pages_ready / inbound.keywords_matched). An agent can tell what this tool does without opening any other 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 description gives some contextual guidance ('Reuse the exact idempotency_key and input after an uncertain mutation') and prerequisites ('Requires webhook.manage'), but it never explicitly says when to choose this tool over test_webhook_endpoint or replay_webhook_delivery. Usage is implied by the name and context rather than stated with alternatives or exclusions.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description adds important behavioral context: HTTPS requirement, 10-second response window, pausing delivery via enabled field, and enumerating all event types. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, followed by necessary details about events and endpoint requirements. It is mostly concise, though the list of event types could potentially be shortened by referring to 'mail lifecycle events' while still being clear.

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

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

Given the presence of an output schema, the description need not explain return values. It adequately covers the tool's configuration purpose, event subscription semantics, and endpoint constraints. However, it could mention idempotency behavior or whether updating one field resets others, though annotations partially cover idempotency.

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

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

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

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

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

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

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

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

The description implies use for webhook configuration but does not explicitly state when to use this tool versus alternatives or when not to use it. It lacks guidance on prerequisites or disambiguation from sibling tools like get_mailbox or list_outbound_mail, which handle different concerns.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=true, openWorld=true, but the description adds genuinely new behavior: the required permission scope, the immutable agent/environment scope, the need for operator authorization before URL redirects, the concurrency protection via expected_revision, and the retry instruction to reuse the exact idempotency_key and input. This is substantive disclosure 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?

Front-loads the updatable field list and constraints, then appends permission, scope and idempotency notes. Dense but each clause carries information; the docs URL is a reasonable pointer rather than 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?

An output schema exists so return values need not be explained, and the description covers auth, scope limits, concurrency and idempotency for a mutation tool with 8 parameters. The one unresolved gap is disambiguation from the sibling update_webhook, which the agent needs in order to pick correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds cross-parameter semantics: expected_revision guards against concurrent overwrite, and idempotency_key must be reused identically after an uncertain mutation. That retry/consistency relationship is not fully captured in the per-field schema 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?

Starts with a specific verb (Update) plus the resource and enumerates exactly which fields can change (name, URL, events, keyword rules, active/paused status). It also names a required parameter (expected_revision) in the first sentence. It does not, however, distinguish this from the sibling update_webhook, leaving the agent to guess which update tool applies.

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 real operating conditions: requires webhook.manage, agent/environment scope cannot be changed, and notifications must not be redirected without operator authorization. It stops short of naming an alternative tool or stating when to prefer this over update_webhook.

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