MCPFax Agent Continuity

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

Goes far beyond the idempotentHint/readOnly annotations by disclosing idempotent retry semantics, new-generation behavior on reuse, timeout envelope delivery, billing via inbox_poll, authentication options, and the exactly-one-enveloe guarantee. 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?

Dense and front-loaded with the core use case and the straggler warning before lower-level details. The only real flaw is minor redundancy, notably FREE being stated twice, but overall every section earns its place for a complex 9-parameter tool.

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

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

Covers the key operational concerns: authentication, billing, timeout behavior, idempotent reuse, and enveloe delivery. The main gap is that there is no output schema and the description only mentions created:false, not the full success return shape, so an agent cannot fully predict the response object.

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 meaningful interaction semantics: min_count and deadline_seconds fire on whichever comes first, participants affect missing-name reporting, outside signals do not count, and reusing barrier_id opens a new generation. This helps an agent reason about parameter combinations beyond the raw schema.

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

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

States a specific verb (create/open) and resource (a join point/barrier) and explains the fan-out/last-finisher-wakes-joiner model. It plainly distinguishes itself from barrier_signal and barrier_status by focusing on creation and lifecycle semantics rather than signalling or status.

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

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

Gives strong context: this is the tool for fanning out to N agents and being woken when the threshold/deadline is met, with clear guidance to set min_count and deadline_seconds because stragglers are normal. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of a 5.

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

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

The description adds extensive behavior beyond annotations: per-participant idempotency, exactly-one notification via a single Durable Object, behavior on already-fired joins, refusal on TTL expiry, non-locking of barrier_id, free usage, and authentication options. This meaningfully exceeds the idempotentHint annotation.

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 longer than average but dense with necessary caveats. It opens with the core purpose and then layers edge-case behavior. The repeated emphasis on FREE is slightly redundant but not harmful; every other sentence adds operational value.

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

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

The description covers the key operational scenarios: normal signal, duplicate signal, already-fired join, timed-out join, and reuse of barrier_id. It also covers authentication. Given no output schema, it mentions the critical refusal outcome but does not describe the success response shape, which is a minor omission.

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 adds value by explaining participant_id idempotency, payload delivery to the joiner, expiry implications for payload, and the agent_key/header relationship. These nuances go beyond 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 clearly states the action ('Report that one participant finished') and the resource (a barrier, identified by barrier_id), and distinguishes the semantics of a signal from other barrier operations. It does not explicitly compare itself to siblings like barrier_create or barrier_status, so it lacks explicit sibling differentiation.

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

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

The description gives strong context about when a signal is valid (fired, expired) but does not advise when to choose this tool over siblings. There is no explicit when-to-use/alternatives guidance, though the implied usage is clear from the action.

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 is unusually transparent: it details exact metering conditions ('$0.002 ONLY when there is real progress... AND the answer has changed'), the no-charge repeat behavior, auth requirements, and the equivalent HTTP route. These go well beyond the annotations and are consistent with idempotentHint=true and 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 is front-loaded with purpose and is information-dense, but it is somewhat redundant: the billing condition is stated twice in similar terms ('$0.002 ONLY when...' and 'Costs $0.002 USDC per call... and ONLY when...'). Trimming that duplication would make it tighter without losing meaning.

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 no output schema, the description carries the burden of explaining return semantics, and it does: it enumerates the reported data, the no-progress case, the no-charge case, and the auth path. For a 2-parameter status tool, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents barrier_id and agent_key fully, including examples and the head-vs-argument preference. The description adds no substantive parameter meaning beyond reiterating the auth option, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a status inspection for a join point, listing the exact information it reports: how many participants signalled, which ones, who is outstanding, and whether completion/timeout envelope has been queued. It is easy to distinguish from barrier_create and barrier_signal by semantic role, though it does not explicitly name or contrast those siblings.

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

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

The opening 'Progress on a join point' implies this is the tool to call when monitoring barrier advancement, and the billing caveats suggest it is a read-style query. However, there is no explicit guidance about when to choose it over alternatives such as barrier_create or barrier_signal, nor any stated 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?

The description discloses billing side effects, idempotent free repeats for unchanged totals, the no-blocking enforcement promise, byte-exact amounts, empty-ledger behavior, and authentication requirements. This goes well beyond what the annotations convey and matches the idempotentHint and non-destructive 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 long but dense, with the core purpose front-loaded and billing behavior structured clearly. Every sentence contributes operational information, though the emphatic no-blocking rhetoric could be tightened without losing meaning.

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 paid tool with no output schema, the description explains return semantics (per-label breakdown, lifetime total, over_limit, empty ledger, byte-exact amounts), billing, auth, and equivalent HTTP route. It stops short of enumerating exact response fields, but an agent has enough to invoke and interpret it correctly.

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

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

Schema coverage is 100%, and all parameters already have descriptions. The tool description adds operational meaning on top: limit is a per-call override, window_seconds has default and max values, and agent_key is a header fallback. This is meaningful value beyond the schema.

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

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

The description states a clear verb, resource, and result: inspect what a unit of work has actually cost, with a per-label breakdown and lifetime total. It is immediately distinguishable from siblings like budget_record, work_status, and heartbeat because it focuses on cost accounting rather than recording, scheduling, or lifecycle state.

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

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

The description gives strong usage context: call it to see accumulated cost, optionally pass a limit to get over_limit, and expect it to never block. It does not explicitly name which sibling to use instead, but the domain and billing details make the targeted use case clear.

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

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

The description goes well beyond the annotations: it discloses append-only behavior, refusal when full, byte-exact decimal handling, no currency conversion, no float usage, exact integer summation, authentication requirements, and that the tool is free. It explains the operation's side effects without needing the schema or hints to carry the burden.

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 each clause carries operational context: append-only, free, exactness, refusal behavior, and auth. It is front-loaded with the core action and scoping. Minor redundancy exists, such as saying FREE twice and restating append-only, which keeps it from a perfect score.

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 6-parameter write tool with no output schema, the description covers auth, free-ness, exactness, failure behavior, and append semantics. The main gap is that it never describes the success response shape or confirm details, which would be useful given there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful precision semantics: amounts are opaque decimal strings stored byte-exact, never converted or rescaled, and totals use exact integer arithmetic. It also explains the purpose of the label relative to budget_check, enriching the structured parameter documentation.

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

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

The description states a specific verb and resource: 'Append one amount to this scope's ledger', and the title 'Record a spend against a unit of work' reinforces exactly what the tool does. It is clearly distinguished from budget_check, the sibling that later 'break[s] the total down', so an agent can tell record from read.

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 makes it clear this tool is for recording a spend by appending to a ledger, and it references budget_check as the consumer of the label. It does not explicitly state when not to use it or route the agent to budget_check for reading, but the context is strong enough to infer the intended 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 declare readOnly, idempotent, non-destructive; the description adds meaningful behavioral context beyond annotations: precise payment conditions, free re-reads, auth requirements, and equivalent HTTP route. It also explains the billing occurs only once per checkpoint version.

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 alternative are front-loaded, but the billing information is repeated redundantly: '$0.002 ONLY when...' appears twice in slightly different form, causing unnecessary length and a run-on feel.

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

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

Covers purpose, alternative, cost/free conditions, not-found behavior, authentication, and HTTP route. Although there is no output schema, 'verbatim what was stored' adequately describes the return shape for this simple fetch 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%, and the input schema already explains both scope and agent_key with examples and usage guidance. The description's mention of agent_key as a header fallback adds little beyond the schema, so a baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Fetch the last checkpoint verbatim — what was stored, with no briefing composed around it.' It also explicitly contrasts with resume_packet, making its distinct role clear.

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 something else: 'Most callers want resume_packet instead, which folds in what arrived while you were gone...' It also covers the not-found case and billing behavior, so the agent knows exactly when this tool is appropriate.

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

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

Annotations only provide readOnly=false, idempotent=true, destructive=false. The description adds substantial behavioral detail: checkpoints without objective/next_action are refused, the body is never parsed/indexed/logged in any mode, privacy_mode:'client_key' means the service cannot read the body and never holds the key, the tool is free, and auth can be a bearer header or agent_key argument. There is no contradiction with 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 front-loaded with the core purpose and each sentence carries real operational information: required fields, size, envelope/body behavior, privacy, auth, and route. It is slightly redundant because 'FREE' appears twice, and the cleartext-envelope detail partially repeats what the schema field tags already say. Overall it is dense but not bloated.

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

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

For a 23-parameter tool with no output schema, the description covers the invocation contract thoroughly: what to save, what is required, how to keep data private, how to authenticate, and how the envelope feeds resume_packet. The main gap is that it never states what the call returns, such as an acknowledgement or checkpoint id, which would help with no output schema present.

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 individual parameters are already documented. The description adds valuable cross-cutting semantics: the envelope/opaque-body distinction, why objective and next_action are enforced, the size guidance, and the confidentiality contract for body/privacy_mode. This raises it above the baseline 3 because it helps the agent know how to treat the parameter groups, not just what each field is.

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 precise verb and resource: 'Save where the work got to, in a STRUCTURED shape so the next invocation can actually act on it.' It also differentiates from siblings by explaining that the envelope is what resume_packet synthesizes from, and that the body is opaque. This makes it immediately distinct from checkpoint_get, work_push, and resume_packet.

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

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

The description gives clear operational context: it is for persisting a structured checkpoint for the next invocation, with objective and next_action required, and it explains auth options and the HTTP route. However, it does not explicitly say when not to use it or name alternatives like checkpoint_get or work_status; the relationship to resume_packet is implied rather than a stated selection rule.

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 idempotentHint=true, and the description substantially expands on this with billing details, free first call, repeated-denial behavior, complete() interaction, granted:null failure semantics, authentication methods, and the equivalent HTTP route. There is no contradiction with the annotations; readOnlyHint=false is consistent with the tool's side-effectful and cost-bearing behavior.

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 densely packed. Core semantics and the critical safety rule are front-loaded, followed by billing and auth details. Some redundancy around the $0.002 billing condition exists, but every sentence contributes meaningful operational 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 no output schema, the description carries the full burden of explaining return values and behavior. It covers granted:true/false/null, first_claimed_at, stored results from complete(), billing conditions, authentication, and the HTTP route. For a tool with this complexity, the agent has enough to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context for agent_key (header fallback) and key (idempotency key), but it does not need to re-explain parameters. It neither detracts from nor significantly enriches the already well-documented schema.

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

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

The description opens with a clear, specific definition: 'Exactly-once guard for work that costs money or has side effects.' It then explains the unique granted:true/false/null semantics, making the tool's function distinct from sibling tools like barrier_status, checkpoint_put, or seen_add without ambiguity.

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

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

The description clearly states when to use the tool: for costly or side-effectful work needing exactly-once protection. It also gives a strong safety rule: if granted:null, you must NOT proceed. It does not explicitly name alternatives or say when not to use it, but the intended context is clear.

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

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

Beyond the annotations, the description discloses that this is a write, that it is free, that refusal returns recorded:false with reason 'no_active_claim', and that the result is an opaque blob never parsed, indexed, or logged. It also adds auth details and the equivalent HTTP route, which annotations do not provide.

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

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

The description is dense and logically ordered: action, exclusions, idempotency, refusal mode, result semantics, then auth. It loses a point because 'FREE' is repeated twice with nearly identical billing claims, adding mild 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 no output schema, the description still specifies the refusal result shape (recorded:false, reason 'no_active_claim') and makes the success path clear by saying a duplicate attempt receives the stored result. It also includes auth, HTTP route, and prerequisite claim context, so an agent has what it needs to invoke the tool correctly.

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

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

The input schema already covers all 4 parameters, so the baseline is 3. The description adds meaning beyond the schema by tying key to the previously claimed key, clarifying that result is opaque, and explaining agent_key as a fallback for hosts that cannot set headers.

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 precise action: 'Attach the outcome to an idempotency CLAIM you hold'. It immediately differentiates from siblings with 'NOT for finishing a mailbox task (use inbox_ack) or a queue item (use work_done)'.

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

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

It explicitly tells agents when to use it (after holding a claim, to store a result) and when not to, naming inbox_ack and work_done as alternatives. It also handles the failure path: re-claim the key first if the claim expired or was never held.

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 critical behavior: expiry actions run EXACTLY ONCE, release_leases uses the same path as a live agent, mark_failed makes resume_packet report an observed death, and the alert is biled only on collection. It also clarifies authentication options. No contradiction with the idempotentHint annotation, since re-beating simply re-arms the same alarm.

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 long, ALL-CAPS-heavy block with the core mechanism appearing only after two philosophical sentences. It repeats the 'FREE' point and is not front-loaded; a compact action-oriented opening would serve an agent better.

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?

It covers auth, costing, expiry side effects, re-arm behavior, and the durability of the alarm. With no output schema, it does not describe the return value shape, which is a minor gap, but overall the tool is well specified enough 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?

The input schema already covers all 7 parameters at 100%, so the baseline is 3. The description adds useful semantic color around on_expiry action ordering and the agent_key fallback, though much of the detail is also present 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 explicitly says each call records a beat and arms a durable alarm for expect_within_seconds, which is a specific verb, resource, and mechanism. The dead-man-switch metaphor and scope semantics make it clearly distinct from liveness-adjacent sibling tools like lease_rene or checkpoint_put.

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 a strong use-case rationale: an agent cannot detect its own death, so an external heartbeat is needed. It explains re-arming and expiry behavior, which implies when to call repeatedly, but it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already mark idempotent and destructive, and the description adds crucial context: acking twice is harmless, a late redelivered ack still succeeds because there is no fence token, unknown task_ids return acked:false, repeating schedules queue the next occurrence, and the result is persisted on a tombstone. 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 dense but every sentence carries a distinct fact: idempotence, rescheduling, tombstone, late-ack behavior, unknown-task response, pricing, authentication, and HTTP route. It is front-loaded with the core purpose before edge cases.

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, no-fence ack operation with no output schema, the description covers the necessary operational context: side effects, error behavior, authentication, cost, and the key alternative. An agent has enough to decide whether to call it and what to expect in the failure case.

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 all four parameters. The description adds meaning beyond the schema by explaining that the result is stored on the tombstone for later duplicates and that agent_key is only a fallback for hosts that cannot set the Authorization header.

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 — 'Acknowledge a task you finished' — and reinforces the scope with the title 'Mark a task done'. It also disambiguates from fenced alternatives by explicitly naming work_take/work_done for refuse-on-lost-ownership, making sibling differentiation clear.

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 when to ack and when not to: ack finished tasks promptly, raise visibility_timeout_seconds on inbox_poll if needed, and switch to work_take/work_done when fenced refuse-on-lost-ownership is required. This explicitly covers a when-not case and an alternative tool.

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

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

Beyond the annotations, the description adds meaningful behavioral context: the tool is free, redelivery of the same task_id is always free, and it explains authentication requirements and the equivalent HTTP route. This goes well beyond what the annotations alone convey.

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

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

The main action is front-loaded and the essential details are present, but 'FREE' and the no-charge point are repeated multiple times, adding redundancy. The authentication and route details are useful but could be tightened without losing value.

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

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

For a tool with three parameters, one required parameter, and no output schema, the description provides sufficient behavioral, authentication, cost, and idempotency context. An agent should be able to decide when to call it and how to invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema already fully documents task_id, agent_key, and delay_seconds. The description reinforces the overall purpose but does not add meaningful parameter-level detail beyond the schema.

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

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

The description states a specific verb and resource: 'Explicitly return a claimed task to the queue'. It also clearly distinguishes the behavior from waiting for the visibility timeout, which makes the tool's role as a nack operation 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 gives clear context for when to use the tool: when you want to hand a claimed task back immediately rather than waiting for the timeout. It does not explicitly name alternative siblings like inbox_ack or work_fail, but the usage context is strong enough for an agent to select appropriately.

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?

Discloses visibility timeout, redelivery behavior, first-delivery-only charging, authentication options, and equivalent HTTP route—details far beyond annotations. No contradiction with the provided annotation 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?

Core behavior is front-loaded, with useful details following. The cost explanation appears twice in slightly different forms, making it somewhat redundant, but every section still carries relevant operational 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 tool with no output schema and minimal annotations, the description covers empty-inbox behavior, charging, redelivery, visibility timeout, authentication, and the HTTP equivalent. An agent has enough information to invoke it and understand consequences 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?

Input schema already describes all 3 parameters at 100% coverage. The description adds minor value by explaining agent_key is a fallback when headers cannot be set and visibility timeout relates to claiming, but does not materially expand parameter 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?

Description states a specific action and resource: 'Collect the next due task envelope from your mailbox' and 'One envelope per call.' This is clear and distinct from the ack/nack siblings, though it does not explicitly name an alternative or exclusion.

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

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

Provides clear context for when to use: when polling for a due task, with follow-up guidance to 'ack it when done' and consequences if not acked. It does not explicitly contrast with sibling tools like claim or work_take, but the mailbox framing makes the intended use apparent.

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 are all false and therefore provide no behavioral safety or idempotency signals. The description adds substantial context: the tool is free, never charges, accepts no callback URL, delivers via inbox_poll on next invocation, and supports two auth methods. This exceeds what the annotations give, though it leaves side effects like dedupe or repeat semantics to 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?

Four sentences that front-load the core purpose and then cover cost, delivery, and auth in a compact way. The word FREE appears twice, a minor redundancy, but the overall description is tight and doesn't waste sentences on 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?

For a tool with 15 parameters and no output schema, the description provides the necessary orientation: what to schedule, how it gets delivered, how to authenticate, and the pricing implication. Itdoesn't cover return values or error cases, but those aren't expected given the absence of an output schema and the schema's own param 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?

The schema already covers 100% of parameters with descriptions and examples, so the baseline is 3. The description only mentions agent_key as an alternate auth mechanism, which is a small addition already reflected in the schema. It adds no new meaning for objective, due_at, in_seconds, repeat_count, or other fields.

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: leave work for your own next invocation. It explicitly compares itself to send() addressed to yourself, which distinguishes it from the sibling send tool and clarifies its self-addressed scheduling purpose. The metaphor in the title reinforces the concept without replacing a functional definition.

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 frames the intended scenario: scheduling work for your own future invocation, with inbox_poll as the retrieval mechanism. It explains why no callback URL is involved, effectively contrasting with webhook-style delivery and implying when this tool is appropriate. It doesn't enumerate exclusion cases or alternatives beyond send(), but the context is sufficiently clear.

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

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

Beyond the annotations, it discloses that cancellation is durable, free, idempotent, cooperative rather than destructive, and changes what work_take and should_continue return. This materially clarifies the destructiveHint=true annotation and prevents the agent from assuming processes are killed.

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 mostly tight and front-loaded, with high-value behavioral detail in each sentence. However, 'FREE and idempotent' is repeated as 'FREE — this tool never charges' near the end, and the HTTP route is optional extra. These are small redundancies, not serious bloat.

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 operation purpose, persistent effect, interactions with siblings, non-kill caveat, idempotency, cost, and authentication. Combined with the rich 100%-covered schema, an agent has enough context to call the tool correctly even without an output schema.

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

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

Schema coverage is 100%, so the schema already documents job_id, reason, and agent_key well. The description adds authentication context and the agent_key fallback option, but this largely mirrors the schema's parameter description rather than introducing new semantics.

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

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

The description states a precise verb and resource: it tells every worker on a job to stop by setting a durable stop flag. It also distinguishes itself from related siblings by explaining how work_take and should_continue behave on a cancelled job. This goes well beyond the title and makes the tool's role unmistakable.

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

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

It frames itself as the only way to stop running agents and explicitly describes the post-cancel behavior of work_take and should_continue, so an agent knows when to choose it. It also sets expectations by saying it does not kill anything, warning the caller not to expect immediate process termination.

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

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

Annotations only indicate readOnly=false, idempotent=true, destructive=false. The description goes far beyond that: it explains refusal vs null semantics, fence as a credential vs generation as an order, dead-man switch recoverability via scope, billing only on first refusal by a holder, and authentication options. This is exactly the operational detail an agent needs and the annotations do not provide.

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

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

The description is long but dense and front-loaded: the first sentence gives the core purpose and the critical refusal warning is capitalized early. Some redundancy exists in the fence/generation explanation and repeated 'do not proceed' warnings, but given the high stakes of distributed locking, the length is largely 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?

With no output schema present, the description compensates by covering all three response possibilities: acquired:true with fence, acquired:false with holder and expiry, and acquired:null as indeterminate. It also covers billing, auth, HTTP route, renewal, and scoping edge cases. For a six-parameter tool with this much behavioral nuance, nothing important 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%, but the description adds significant meaning beyond the schema. It explains why fence is a credential and never predictable, why holder must be unique per live instance, why scope makes a lease recoverable, and how omitting fence causes a refusal rather than renewal. This materially improves correct parameter usage.

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: 'Acquire a mutual-exclusion lease' and immediately states the purpose: 'Mutual exclusion so two instances of the same agent do not both process one item.' It clearly distinguishes the tool's core behavior from siblings like lease_release and lease_renew through acquired states, renewal rules, and refusal semantics.

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 strong contextual guidance: use this to lock a resource before processing, renew by presenting the fence, and do not proceed on acquired:false or null. It also explains when a lease is refused vs renewed. However, it never explicitly names sibling tools like lease_renew or lease_release as the alternative for those actions, so it stops short of a 5.

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

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

The description goes well beyond the annotations, detailing exact failure modes (stale fence, expired lease), result fields (released:false, reason, current holder), retry semantics, and side effects on the scope ledger and resume_packet. It also discloses authentication requirements and the equivalent HTTP route. No contradiction with the annotations is present.

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

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

The description is dense and front-loaded with the core purpose, then flows through failure modes, side effects, and authentication. The repeated FREE statements are slightly redundant, but otherwise every sentence adds necessary behavioral or operational detail. It is longer than minimal, but the complexity of lease semantics justifies most of the length.

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

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

Given the tool's subtle failure semantics and lack of an output schema, the description thoroughly covers what an agent needs to know: when release succeeds, when it refuses, what the returned reasons mean, whether to retry, how release affects later agents, and how to authenticate. This is a complete picture for a lease-release mutation.

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 schema already explains key, holder, fence, and agent_key in detail. The description adds context around agent_key usage and fence validation, but it does not substantially improve on the schema. The baseline of 3 applies because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource: 'Release a lease you hold so the next worker can take it immediately instead of waiting for the TTL.' This clearly distinguishes the tool from lease and lease_renew by emphasizing handoff and immediate availability. It also clarifies what release is not: it refuses to free someone else's lock.

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

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

The description gives clear context for when to use release: when you hold a lease and want the next worker to proceed without waiting for the TTL. It also provides important post-call guidance, such as treating 'not_holder' as having lost the lock and stopping work. It does not explicitly compare against lease_renew or lease, but the intended usage 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?

The description adds substantial behavioral context beyond annotations: it is free, it fails with renewed:false on expiry or takeover, it preserves fence and generation, and it corrects the scope ledger so downstream systems see the real expiry. This is exactly the kind of operational nuance annotations like idempotentHint do not capture.

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 longer than average but every sentence adds operational value: free, failure semantics, token preservation, ledger correction, and auth. The FREE point is repeated, which is mild redundancy, but the structure is front-loaded with the core action and most critical caveats first.

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 lease-renewal tool with no output schema, the description covers the failure response, side effects, authentication, and HTTP route. It does not spell out the successful response shape in detail, but it provides enough for an agent to invoke correctly and interpret the key failure case.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that the fence token is drawn independently per acquisition and cannot be derived or reused from an earlier lease, which adds real meaning beyond the schema. It also clarifies the agent_key parameter's role as a fallback when headers cannot be set.

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: 'Extend a lease you still hold' with the fence token. This clearly distinguishes it from lease_release (letting go) and lease (acquiring), and the title reinforces the same meaning without being a pure tautology.

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?

Describes when renewal succeeds and when it fails: if the lease expired or was taken, treat it as lost and stop work. It implies the appropriate use case—extending a lease you still hold—and warns about the lost-lock condition, though it does not explicitly name sibling alternatives or state 'use this instead of X'.

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 goes well beyond the annotations by disclosing that the secret is never stored, cannot be recovered if lost, that the tool is free, and how to authenticate afterward. However, it claims the agent_key can be passed as an argument, which contradicts the schema's additionalProperties: false and the actual listed parameters, making part of the behavioral guidance unreliable.

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

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

The purpose is front-loaded and the operational details are useful, but the description repeats 'FREE' twice, and the auth/route details could be more compact. Overall, it is reasonably structured for a credential-creating tool.

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

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

The description covers return values, secret storage, cost, and authentication, which is good for a 2-parameter tool with no output schema. However, it does not clarify whether agent_id may be omitted, what happens on duplicate registration, or the exact return format, and the agent_key instruction is misleading.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds no genuinely useful parameter-level meaning and instead introduces a non-existent 'agent_key' argument. It also uses the term agent_secret for the returned credential while the schema defines an optional input parameter of the same name, which can confuse whether the secret is supplied or generated.

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 durable identity for an agent' — and clarifies what is returned (agent_secret, public agent address, namespace id). This is clearly distinct from the sibling tools, which all operate on an already-registered agent for messaging, work, budgeting, or barriers.

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

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

The description implies this is the first-step registration tool by saying it creates a durable identity and returns credentials, but it never explicitly states when to use it versus alternatives, whether it should be called once per agent, or what happens if an identity already exists. No exclusion or alternative guidance is 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?

Beyond the annotations, the description discloses payment semantics, cost conditions, empty-scope behavior, authentication methods, and the equivalent HTTP route. It also clarifies idempotent-like behavior by stating that recomposing the same briefing is free, which adds real context beyond 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 front-loaded with the core value proposition and return contents, followed by important operational details. It is somewhat long and repeats the billing condition in two places, but each detail about cost, auth, and response format earns its place for a paid tool.

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

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

Given the tool has no output schema, the description compensates by listing the briefing fields, data sources, response format, cost, auth, and empty-scope behavior. An agent has enough guidance to invoke it correctly and interpret the result, even without a formal output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description adds some context about scope and empty scope behavior, but it does not substantially extend the meaning of the parameters beyond what the input schema provides.

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

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

The description names a clear verb and deliverable: it returns a briefing, not an archive, and enumerates its contents. It also distinguishes itself from a raw checkpoint and from a conversation resume, making its role as the headline resumptool 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 positions itself as 'THE HEADLINE TOOL' for resuming work and explains that it combines checkpoint data with server-observed facts, implicitly distinguishing it from checkpoint_get. However, it does not explicitly name alternatives or state when not to use it, falling just short of direct 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?

The description is richly transparent about billing, auth, write behavior, and determinism, but it directly contradicts the idempotentHint:true annotation. It states that record:true counts a new attempt, produces a genuinely new answer, and is billable again, meaning repeated identical calls are not idempotent. Per rubric, a description that contradicts annotations scores 1.

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, but the billing conditions are explained twice in near-duplicate passages ('$0.002 ONLY when...' and 'Costs $0.002 USDC per call... ONLY when...'), adding meaningful bloat. A single consolidated billing statement would have been clearer and shorter.

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 values, auth, HTTP route, read/write modes, TTL default, and billing despite having no output schema. However, the contradictory idempotency annotation leaves an agent unsure whether retrying a record:true call is safe, and the 'deterministic suggested backoff' is not detailed enough to fully compensate for the missing output schema.

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

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

Schema coverage is 100% with examples for all five parameters, so the baseline is 3. The description adds meaning beyond the schema by explaining that record:true is a WRITE with billing consequences, while record:false is a non-mutating read, and by linking scope to resume_packet reporting.

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 resource ('durable retry bookkeeping') and a clear purpose: return attempt count, first/last attempt times, and deterministic suggested backoff so retries survive a crash. This clearly distinguishes retry_state from the sibling checkpoint, barrier, heartbeat, and work-management 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 gives clear context for when to use the tool: durable retry bookkeeping after a session dies. It also instructs when to pass record:true (count this attempt) versus the default record:false (read history without changing it). It does not explicitly name sibling alternatives or when-not-to-use conditions, so it misses full alternative guidance.

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

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

Beyond the annotations, the description discloses material behavior: privacy via salted SHA-256 digests, inability to read/list/reconstruct stored items, the 10,000-entry capacity, refusal-on-full instead of silent drops, auth requirements, and the no-charge guarantee. These are exactly the operational details an agent needs, and none contradict the annotations.

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

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

The description is front-loaded with the core purpose and leads into privacy, capacity, then auth. The only real waste is repeating FREE twice, which is redundant but does not obscure meaning.

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

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

For a 5-param mutation tool without an output schema, it covers invocation, auth, capacity/refusal semantics, and storage guarantees. It does not describe return/response values or duplicate-item behavior, but idempotentHint covers idempotence and the documented capacity/auth details are the most important parts for correct invocation.

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

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

Schema coverage is 100%, but the description still adds param-relevant meaning: a set holds up to 10,000 entries and warrants rotation when full, and agent_key is positioned as an auth fallback. It does not cover scope or ttl_seconds in prose, but the schema already documents those clearly.

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 ('Record') and resource ('items you have already processed'), and it clearly explains the deduplication/membership semantics with 'can test membership' and 'deduped'. This distinguishes seen_add from siblings like seen_check, which is the membership-query side.

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 conveys when to record processed items and gives conditional guidance ('when full... rotate to a new set name'), but it does not explicitly say when not to use this tool or direct the agent to a sibling like seen_check for membership tests. Usage context is inferable rather than stated as a decision rule.

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

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

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses the unusual billing behavior, the idempotency nuance ('asking the same question again while the set has not grown is free'), authentication options, and the equivalent HTTP route. This gives the agent substantial operational context 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?

The first sentence is excellent and front-loaded. However, the billing condition is stated redundantly: '$0.002 ONLY when we filter at least one item out...' is followed later by 'Costs $0.002 USDC per call via x402 on Base, and ONLY when filtered_count >= 1...' The paragraph is information-dense but could be tightened.

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

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

For a three-parameter tool with no output schema, the description covers invocation semantics, authentication, cost behavior, and what the result means. It does not specify the exact response shape, but it does describe the outcome well enough for an agent to select and interpret the call correctly.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying that agent_key is a fallback only when headers cannot be set, that the header is preferred, and that items are capped at 100 strings. These details go beyond the schema's examples.

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: 'Given a batch of items, return only the ones not already in the set.' This clearly defines a filter operation and distinguishes it from sibling tools like seen_add, which would add items to the set rather than check them.

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 strongly implies when to use the tool: when you need to determine which items from a batch still need processing. It adds practical conditions like the 100-item limit and the free-call behavior when nothing is new. It does not explicitly mention seen_add as the alternative for recording seen items, so it stops short of a full when-to-use vs alternative statement.

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 adds substantial behavioral context: the tool is free, it can never read another mailbox, mailboxes have hard capacity limits, and the last 32 slots protect safety notifications. It also documents authentication requirements and the equivalent HTTP route.

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

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

The description is front-loaded with the core purpose and remains efficient for a tool with 15 parameters. The main flaw is redundancy: 'FREE' appears twice, and the auth/route section could be tighter, but overall the length is justified by the operational context.

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

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

For a complex mail-sending tool with no output schema, it covers workflow, mailbox quotas, safety guarantees, authentication, and transport semantics well. The detailed parameter behaviors are left to the schema, which covers them fully. The main gap is the lack of any description of return values or failure behavior.

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 schema already carries most param semantics. The description adds useful context by framing objective, context, attachments, and history as an envelope that lets the receiving agent rebuild state, but it does not add per-parameter details beyond the schema.

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

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

The description names a specific action and resource: 'Queue a rich task envelope addressed to any registered agent.' It also distinguishes itself from polling tools by saying 'Nobody waits and nobody polls,' making it clear this is the asynchronous send side of the mailbox system.

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 establishes the use case: agent-to-agent asynchronous mail delivery. It also warns against using this tool to read another agent's mailbox. However, it does not explicitly name sibling alternatives like inbox_poll or work_push, so the comparison guidance is mostly implicit.

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

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

The description goes well beyond the idempotentHint annotation: it explains that only the first cancellation is billed, later 'no' answers are free, keep-going answers cost nothing, unknown jobs answer keep-going, and failures return continue:null for retry. It also discloses the x402 billing mechanism and the Authorization/agent_key requirement, so the cost and side-effect profile is fully transparent.

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

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

The description contains several useful caveats, but it is wordy and somewhat duplicative: the 'only billed on the first no and never again' idea appears twice. The first sentence is also awkwardly phrased, and the text could be tightened while keeping auth, billing, and failure-mode facts.

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 small two-parameter tool with no output schema, the description covers the full behavioral contract: how to interpret the answer, what to do on null, billing implications, authentication, and the equivalent HTTP route. An agent has enough information to invoke and react to the result 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 already covers both parameters well (100% coverage), including job_id aliases and agent_key preferred usage. The description adds the header-vs-agent_key authentication preference but does not materially expand parameter semantics beyond the schema.

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

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

The description and title clearly identify this as a per-item continuation check for a job, returning 'keep going', 'no/stop', or a null failure state. It names the job resource and the between-items usage context, though it does not explicitly contrast with siblings like work_status or checkpoint_get.

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 a clear usage context: a worker calls it between items, and it instructs retrying when the state cannot be determined rather than guessing. It does not name explicit alternatives or exclusions, but the intended situation is clear enough.

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

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

Annotations already mark this read-only and idempotent, and the description enriches that with billing behavior, free re-reads, the no-watermark case, authentication requirements, and the exact cost trigger. It also confirms the route. This goes well beyond annotations without contradicting them.

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

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

The core purpose is front-loaded, but the billing explanation is repetitive: the $0.002 condition is stated multiple times in slightly different forms. The description is useful but would be tighter if the cost rules were consolidated into one sentence.

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 main call context, empty-watermark behavior, auth, HTTP route, and billing. With no output schema, it does not spell out the exact response shape, but it clearly implies the returned position and the no-watermark notification. This is complete enough for a simple read tool backed by strong 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 the baseline is 3. The description does mention passing agent_key when headers cannot be set, but this largely duplicates the schema's own guidance. No significant new parameter-level semantics are added beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Fetch the position you last recorded for a stream.' It clearly distinguishes this from watermark_set (writing a watermark) and other state tools by explaining the upstream/new-items use case. The title is colloquial, but the description removes ambiguity.

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

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

The description gives clear context for when to use the tool: before asking an upstream for only what has changed since the last recorded position. It does not explicitly name alternative tools or exclusion conditions, but the usage intent is strong and paired with watermark_set as an obvious sibling.

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 that the position is an opaque string stored verbatim and never interpreted, that the tool never charges, and how authentication can be done. These are useful behavioral details not present in the schema or annotations. There is no contradiction with 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 opening sentence is front-loaded and useful, and the auth/route notes are practical. However, FREE appears twice with effectively the same claim, which is redundant and slightly weakens the structure.

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 two required parameters, full schema coverage, and idempotentHint, the description covers the core behavior, storage semantics, cost, authentication, and HTTP route. It does not describe return values or overwriting behavior, but no output schema exists and the idempotentHint makes that less critical.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds a little context for position (stored verbatim, never interpreted) and auth guidance, but it does not meaningfully expand parameter semantics beyond what the schema provides.

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

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

The description states a specific action — record how far you got through a stream, feed, or table — and a concrete outcome: the next invocation knows where to start. It is not a tautology, but it does not explicitly contrast with sibling tools such as watermark_get or checkpoint_put, so differentiation relies mostly on the tool name.

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 a clear use case: persist a resume position so future invocations can continue from that point. It also covers the authentication prerequisite. However, it does not name alternatives or say when not to use this tool, 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?

Beyond the readOnlyHint/idempotentHint annotations, the description adds critical behavioral context: the tool never charges, authentication can be done via header or agent_key, and the equivalent HTTP route is provided. These are meaningful traits an agent cannot infer from the schema alone.

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

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

The description is front-loaded with the tool's outputs and stays organized. However, the FREE point is made twice ('FREE, deliberately' and 'FREE — this tool never charges'), which is slightly redundant, though the emphasis may be intentional.

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 no output schema, the description compensates by listing all returned values: address, registration time, item counts, due-now count, next due time, and dead-letter count. It also covers cost, auth, and routing, making the tool self-sufficient for an agent.

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 single optional parameter agent_key is already fully described in the schema (its purpose and preference over the header). The description repeats this guidance without adding new parameter semantics, so the high schema coverage baseline 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 names a specific action ('Report') and resource ('this namespace's public address, registration time, and mailbox counts'), then enumerates the exact counts returned. This clearly distinguishes the tool from siblings like work_status or inbox_poll.

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

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

The description gives clear usage context: poll this tool for free before paying to collect work. It implies the alternative is a billable collection/envelope action, though it does not explicitly name a sibling tool, so it stops short of a perfect 5.

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

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

Annotations provide destructive/idempotent hints, and the description adds substantial non-obvious behavior: calls are FREE, past-lease completions are refused with lease_lost and ignored, fence-less calls on re-hand-out items are refused with fence_required, the result is opaque and never parsed, and it is surfaced later by work_status. It also documents auth via header or agent_key fallback. This is exactly the kind of context agents need beyond annotations and 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 long but information-dense, front-loading the core purpose and zero-cost fact. Nearly every sentence adds a distinct behavioral or auth detail, though 'FREE' appears twice and the HTTP route is slightly secondary. Overall it earns its length without being bloated.

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

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

Given the param count, the fence/lease complexity, and the absence of an output schema, the description covers the key invocation concerns: what to provide, what errors to expect, auth, cost, and side effects on result visibility. The only real gap is that it does not say what a successful call returns, which would be useful since no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it explains the purpose of the fence token, the consequence of an expired lease, and that the optional result is returned by work_status for parent progress. It also clarifies agent_key as a header fallback. The params themselves are already well described in the schema, so extra credit is modest but real.

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 action and resource: 'Complete an item you hold.' It clearly identifies successful completion rather than failure, and its references to work_fail are limited to shared fence/lease error behavior, so the agent can distinguish this from the failure-reporting sibling. The title also reinforces the purpose.

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

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

The description implies the right time to call: when the agent holds the item and has finished it. It explains when the call will be refused (lease_lost, fence_required), but it never explicitly contrasts this tool with work_fail or the sibling 'complete', nor states 'use this for success, use work_fail for failure.' That leaves usage selection somewhat implied rather than explicit.

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

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

Adds substantial behavioral context beyond annotations: dead-lettering and surfacing in work_status, permanent failure when retry:false, 'CANNOT BE UNDONE', refusal codes (lease_lost, not_holder, fence_required), and the never-silently-dropped guarantee. DestructiveHint true is consistent and expanded with concrete consequences.

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

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

The description is dense and information-rich, with purpose front-loaded. However, it repeats 'FREE' twice and uses heavy capitalization that adds noise. Though a bit sprawling, every major behavioral 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?

Covers authentication, side effects, error/failure modes, and dead-lettering thoroughly, including edge cases. The only gap is the absence of any mention of the success response shape, which matters because there is no output schema; still, for invocation and failure handling, it is nearly complete.

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%, but the description adds valuable runtime semantics beyond the schema: the default and effect of retry, the fence validation rules with specific refusal conditions, the error's role on the dead letter, and the agent_key/Authorization header alternative. This materially helps an agent set parameters correctly.

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: 'Report that an item did not work out.' It clearly distinguishes itself from siblings by explicitly noting 'there is no work_release' and positioning itself as the correct way to hand an item back even when nothing went wrong, in contrast with work_done and other work-family 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?

Gives explicit when-to-use guidance: it is also the correct way to return an item when nothing went wrong because there is no work_release. It also explains when to use retry:true vs retry:false and references work_done's fence behavior, giving clear routing across sibling tools.

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

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

The description goes well beyond annotations: it specifies idempotency is per item_id, duplicate pushes add once, payloads are opaque and never parsed, authentication can be via Authorization header or agent_key, and the tool never charges. It does not contradict the annotations, though it omits response/failure behavior.

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 written in all-caps marketing voice, repeats 'FREE' twice, and buries authentication near the end. It contains useful information but is not appropriately sized or front-loaded for an MCP tool definition.

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

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

Combined with the 100% parameter schema and annotations, the description covers batching, repeated pushing, idempotency, opaque payloads, auth, and the no-coordinator model. It does not describe return values or explicitly point to consumer siblings like work_take, but those are minor gaps for this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining agent_key usage context, idempotency semantics for item_id, and that payloads are opaque, which enriches the meaning of the items parameter beyond the schema.

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

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

The title and description clearly state the operation: enqueue work items onto a durable queue, with a concrete usage pattern of pushing up to 100 items and repeating until the batch is queued. It does not explicitly distinguish from sibling tools like work_take, though the push/pull split is obvious from names.

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 when to use this tool: instead of writing custom work-distribution code, push items and let workers pull independently. It gives a clear usage pattern and mentions idempotency for retrying parents, but it does not explicitly say 'do not use for pulling' or name sibling alternatives.

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

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

Reveals billing behavior, exact scanning-based counts, free paging, authentication requirements, and idempotent-like billing semantics far beyond what annotations provide. The description is consistent with annotations; charging aligns with readOnlyHint false and idempotentHint true.

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

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

Front-loaded with the main value and packed with useful details, but the pricing condition is repeated twice and the all-caps sentence adds flavor rather than necessity. It could be tightened without losing meaning.

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?

No output schema exists, so the description correctly carries the burden of explaining result content: count categories, results, dead-letter errors, 50-row windows, page tokens, auth, and cost. An agent has enough information to invoke the tool and interpret its response.

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?

Input schema already documents all four parameters with descriptions and examples, so the baseline is 3. The description adds small context like free paging and opaque tokens, but most parameter meaning already lives in the schema.

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

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

States a specific verb and resource: report fan-out progress counts, collected results, and dead letters with errors. The phrase 'THIS IS WHAT LETS A PARENT PROCEED WITH 4 OF 5' makes the operational purpose concrete and distinguishes it from generic status 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?

Gives an explicit when-to-use scenario: a parent should call this to continue with partial success instead of blocking on a straggler. It does not name alternatives or state when not to use, but the context is clear enough for an agent to select it correctly.

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

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

Annotations give only generic hints, but the description discloses the important behavioral traits: items are leased not deleted, single-owner exclusivity, per-item fencing, lease expiration returning items, and first-time-only billing. There is no contradiction with 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?

Important information is front-loaded and logically grouped, but the $0.002 pricing condition is stated twice and several sentences are long and run-on, making the description more verbose than necessary for an agent 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?

Even without an output schema, the description covers edge cases, recovery behavior, fencing, cost, authentication, and the equivalent HTTP route. An agent has enough behavioral contract to call the tool correctly and know what to expect.

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

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

Schema coverage is already 100%, but the description adds real meaning: it links holder and lease_seconds to the lease/fence model, explains agent_key as a header fallback, and clarifies what 'take n items' means in terms of leased items rather than deleted items.

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 action and object: 'Take up to n items' and immediately distinguishes itself by saying 'LEASED not deleted'. It clearly positions this tool against the lease family and against work_push/work_done/work_fail.

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 rich context for when to call it: lease semantics, expiry on worker death, empty/cancelled queues, auth options, and conditional billing. It does not explicitly list sibling alternatives to avoid, but the behavior is specific enough that the agent will not confuse it with push/done/fail/status.

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