MCPFax Agent Continuity

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

The description goes far beyond the annotations. It discloses idempotency nuances, guaranteed timeout delivery, free billing, write-only notify_address, plain-text barrier_id storage, and the fact that out-of-roster signals do not count. This is exactly the behavioral context an agent needs, and it does not contradict the annotations.

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

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

The description is information-dense and front-loaded, but it is also bloated: 'FREE' appears twice, the all-caps warning is long, and some clauses repeat the same idea. It is structured enough to follow, but it would benefit from tightening.

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 9-parameter mutation tool with no output schema and minimal annotations, this description is exceptionally complete. It covers lifecycle, idempotency, timeout behavior, billing, authentication, and notification semantics, leaving little ambiguity for an agent deciding whether and how to call it.

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

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

The schema already covers all 9 parameters at 100%, and the description adds meaningful semantics on top: min_count/default/expected_count interaction, deadline_seconds bound to TTL, write-only notify_address, and the plain-text nature of barrier_id. Not every parameter is re-explained in prose, but the key nuances are there.

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?

Name and title clearly identify the action: opening a join point for fan-out work. The description adds the specific 'last one to finish wakes the joiner' semantics and distinguishes the tool from siblings like barrier_signal and barrier_status by focusing on creation and lifecycle reuse.

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 rich contextual guidance: when to fan out work, when to use min_count/deadline_seconds, what happens on timeout, and how reusing a barrier_id creates new generations. It does not explicitly name alternatives or state 'use X instead of Y', but the sibling names plus this context make the intended usage 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 (idempotentHint=true), the description reveals significant behavioral context: the Durable Object design ensures N simultaneous signals produce exactly one notification; already-fired joins still record the signal but cannot double-fire; expired joins refuse with signalled:false and reason 'expired'; and the tool is free. No contradictions with annotations.

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

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

The description is long but every section adds value: core action, idempotency, concurrency, edge cases (already-fired, expired), and auth/route. It's front-loaded with the primary verb and uses headers-like caps (FREE, IDEMPOTENT) to highlight key properties. No redundant sentences.

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 tool with no output schema, the description covers behavior thoroughly (edge cases, failure modes, and next steps). However, it does not explicitly state the response shape for a successful signal (only references signalled:false in the expiry case), leaving a minor gap in expectations. Overall it's sufficiently complete for most use cases.

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?

Although the input schema covers all 4 parameters (100% coverage), the description adds semantic meaning: it explains that payload is 'what the joiner will receive' and that on expiry the payload will not reach the joiner ('your payload did NOT reach the joiner'), and it ties participant_id to the idempotency behavior. It does not add syntax details but clarifies the lifecycle implications, so it goes beyond the schema baseline of 3.

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

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

The description opens with a specific verb+resource: 'Report that one participant finished, optionally attaching a payload the joiner will receive.' This clearly distinguishes it from sibling tools like barrier_create and barrier_status, which handle creation and status checks respectively. The scope (one participant at a time) is explicit.

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

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

Provides explicit when-not and alternative guidance: signals to a timed-out or TTL-passed join are refused with reason 'expired', and in that case the caller should 'call barrier_create with it to open a new generation.' Also notes the idempotency property ('the same participant_id signalling twice counts once'), which informs safe retry behavior. It doesn't explicitly compare with barrier_status, but the guidance is concrete.

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

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

The description goes beyond annotations by disclosing the billing behavior (only charges when new progress exists and not previously billed), authentication requirements (Bearer header or agent_key), and the HTTP route. It also clarifies that an untouched barrier or repeated answer is free and says so. This adds substantial context beyond readOnlyHint/idempotentHint.

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 thorough but contains redundancy: the billing rule is stated twice with nearly identical wording ('$0.002 ONLY when...' and 'Costs $0.002 USDC per call... ONLY when...'). The content is front-loaded and structured, but the repetition could be trimmed.

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

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

With no output schema, the description must convey the return shape. It does so by listing the progress components (count, which participants, outstanding, envelope state). It also covers billing and authentication, making the tool's behavior fully understandable in context.

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?

Parameter schema coverage is 100%, so baseline is 3. The description adds meaning for agent_key by explaining when to use it (if host cannot set headers), and it reinforces barrier_id usage through the context of inspecting a join point. It doesn't add extensive new detail, but the auth guidance is valuable.

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: reporting progress on a join point, including counts, which participants signaled, who is outstanding, and whether completion/timeout is queued. This uses a specific verb ('progress on') and resource ('join point'), and it naturally distinguishes from sibling tools like barrier_create and barrier_signal.

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

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

The description gives clear context for when the tool is useful (inspecting barrier progress) and explains the billing condition—when it costs money and when it does not. However, it does not explicitly mention alternatives or when not to use it, though the purpose is fairly 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 goes far beyond annotations. It discloses billing behavior ($0.002 USDC per call, conditions when charged), idempotent-like behavior (unchanged total is free), authentication requirements, and edge cases (empty ledger costs nothing). It also clarifies the tool never blocks. 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 longer than typical but every sentence carries important information about billing, limits, and authentication. It is front-loaded with the core purpose. Some phrasing like 'we will not pretend to an authority we do not have' is slightly theatrical, but the overall structure is efficient and justified given the complexity.

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

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

Given the tool's complexity (billing side effects, authentication, multiple conditions) and lack of output schema, the description is remarkably complete. It covers return semantics (byte-exact, over_limit, empty ledger behavior), cost model, and authentication methods. An agent can fully understand how to invoke and interpret 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 baseline is 3. The description adds some context for 'limit' (pass one here) and 'agent_key' (if host cannot set headers), but does not significantly improve parameter understanding beyond the schema's own descriptions. It earns a solid 3.

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

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

The description clearly states the tool's purpose: 'What this unit of work has actually cost across every session, with a per-label breakdown and a lifetime total.' It also distinguishes itself as a reporting/checking tool (not an enforcement tool) with 'WE REPORT, WE NEVER BLOCK.' This is a specific verb+resource combination that differentiates from siblings like budget_record.

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

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

The description provides clear usage context: when to use (checking costs against limits), behavior when limits are exceeded, and billing conditions. It implicitly excludes using it for enforcement ('enforcement is the caller's decision'). However, it does not explicitly name alternative tools like budget_record, missing the 'alternatives' component for a 5.

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

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

Annotations only set false hints, so the description carries the safety burden. It discloses FREE/no charge, APPEND-ONLY semantics, refusal when full, byte-exact decimal storage, and auth via Authorization header or agent_key, all beyond annotations.

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

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

The description is longer than typical but front-loads the problem statement and key constraints. It repeats 'FREE' twice and includes route info that is useful but not essential, so not perfectly concise.

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

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

Covers purpose, append-only behavior, storage format, auth, retention/ttl context, and failure mode when full. It does not describe the response shape, but with no output schema and a simple side-effect tool, this is a minor gap.

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 already covers all 6 params with examples, so baseline is 3. Description adds cross-cutting semantics: amount is an opaque decimal string stored byte-identical, refunds are allowed via negative values, limit is never enforced, and agent_key is a fallback to the 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?

Description uses specific verb 'append' and resource 'ledger' for a scope, explicitly stating it records spend against a unit of work. This clearly differentiates it from sibling budget_check, which presumably reads the same ledger.

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

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

The description opens with the problem of invisible spend and says to append one amount, making the intended use obvious. It does not explicitly name budget_check as the read-side alternative, so exclusion guidance is implicit 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?

The description adds substantial behind-the-scenes behavior beyond annotations: the billing model ($0.002 only when found and version changed), free re-reads, and behavior when no checkpoint exists. It also documents authentication requirements via header or agent_key argument. This complements the readOnlyHint and idempotentHint 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 purpose, but the billing details are repeated twice ('$0.002 ONLY when...' and 'Costs $0.002 USDC per call...') making it somewhat redundant. However, it remains organized and informative.

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?

Despite lacking an output schema, the description covers the essential context: the tool's purpose, its relationship to resume_packet, billing, authentication, and the equivalent HTTP route. This is more than sufficient for an agent to select and 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 both parameters with descriptions and examples (100% coverage), so the description need not add much. The description does clarify that agent_key is an alternative to the Authorization header, which aligns with the schema. No additional parameter meaning is added.

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

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

The description explicitly states the tool fetches the last checkpoint verbatim, without a briefing, using a specific verb and resource. It also distinguishes it from resume_packet by noting that most callers should use that alternative instead.

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

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

The description provides clear guidance on when not to use this tool: 'Most callers want resume_packet instead' and explains what resume_packet offers. It also implies usage for raw checkpoint retrieval, and optionally mentions authentication 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?

The description goes well beyond the annotations, disclosing that the tool is FREE, that the BODY fields are 'never parsed, indexed or logged in any mode,' that privacy_mode 'client_key' means the provider cannot read the body, and that authentication can be via Authorization header or agent_key. The HTTP route is also provided. These are significant behavioral traits not visible in annotations, and 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 dense and well-structured, with key concepts highlighted (ENVELOPE, BODY, FREE, REQUIRED) and information front-loaded. It contains some redundancy ('FREE' appears twice) and is slightly long, but every sentence carries useful information about behavior, constraints, or security, so the length is justified.

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

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

For a 23-parameter, write-side tool with no output schema, the description is exceptionally complete. It explains the envelope/body architecture, required fields, size guidance, privacy modes, authentication, HTTP route, and the tool's relationship to resume_packet. This covers all key aspects an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining the ENVELOPE vs BODY distinction, the requirement for objective/next_action, and the 'schema is the guardrail' rationale. It also clarifies privacy_mode behavior and ttl_seconds retention. This meaningfully augments the schema descriptions without duplicating them.

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

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

The description clearly states the tool's function: 'Save where the work got to, in a STRUCTURED shape so the next invocation can actually act on it.' It uses a specific verb ('save') and resource ('work state'), and distinguishes itself from the sibling tool resume_packet by noting the envelope is what resume_packet synthesizes from. This provides clear differentiation from the read/resume 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 gives clear context on when to use this tool (to checkpoint structured work state for the next invocation) and implies it is the write counterpart to checkpoint_get/resume_packet. It also provides practical guidance: 'Work state is small: aim for a few kilobytes,' and warns that vague checkpoints are refused. However, 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?

The description richly discloses behavior beyond annotations: billing conditions ($0.002 charged only on first denial per key, free subsequent denials), the granted:null uncertainty case, and authentication requirements (Bearer header or agent_key argument). Annotations only say idempotentHint=true and readOnlyHint=false, leaving the safety and cost details entirely to the description, which handles them thoroughly.

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, front-loading the core purpose and then expanding on costs, state semantics, and auth. There is some redundancy in the cost explanation ('repeated denials... free' vs. 'the same call returns the full answer and settles nothing'), but overall each section earns its place given the tool's complexity.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers granted:true/false/null, first_claimed_at, stored result from complete(), cost details, and auth. For a billing-sensitive tool with side effects, this is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining the agent_key parameter as an alternative to the Authorization header, and mentions key scoping and hashing. This goes slightly beyond what the schema already states, providing practical usage nuance.

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 'Exactly-once guard for work that costs money or has side effects', which clearly states the tool's purpose and scope. It further distinguishes itself by explaining the granted:true/false/null states, making it clear this is an idempotency claim tool, not a generic read or write. This differentiates it from siblings like seen_check or lease.

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

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

The description explicitly states when to use: 'for work that costs money or has side effects' and for retrying agents to avoid paying twice. It also warns against proceeding when granted:null. However, it does not explicitly name alternative tools or say when not to use it, though the context strongly implies its niche.

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 (idempotentHint=true), the description discloses that this is a write operation, never billed, and how failures are handled (recorded:false, reason 'no_active_claim'). It also states the result is an opaque blob never parsed/indexed/logged, and explains authentication methods. 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 well-structured with purpose first, then exclusions, idempotency behavior, failure semantics, and auth. It is slightly redundant by mentioning 'FREE' twice and could be tightened, but every sentence otherwise carries essential information.

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

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

Despite lacking an output schema, the description explains the failure mode (recorded:false with reason), the idempotency guarantee, the opaque result handling, and authentication options. It covers all relevant operational aspects an agent needs to decide and invoke correctly, making it complete for this tool's complexity.

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

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

The input schema already has 100% description coverage for all parameters. The description adds valuable context about key reuse ('same key you claimed'), the opaque nature of the result, and clarifies status defaults not fully explicit in the schema. This goes beyond the schema, so a small uplift from baseline is warranted.

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

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

The description uses a specific verb and resource ('Attach the outcome to an idempotency CLAIM') and immediately distinguishes this tool from siblings by naming inbox_ack and work_done as alternatives for other task types. This leaves no ambiguity about what the tool does.

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

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

Explicitly states when to use the tool (when you hold an idempotency claim) and when NOT to use it, pointing to alternatives. It also covers edge cases like expired claims and re-claiming, providing clear decision-making 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 discloses many behavioral traits beyond annotations: expiry actions run exactly once, actions run in a specific order, billing details (beat is free, alert billed only on collection), and the release_leases blind spot. It also mentions auth methods and the write-only nature of notify_address. These details add significant context 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 well-structured: it starts with the core concept, then mechanics, then parameter details. It front-loads the purpose and provides necessary caveats. Slight redundancy in billing statements ('FREE — it is a write' repeated as 'FREE — this tool never charges') could be trimmed, but overall it stays informative.

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

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

Given the tool's complexity (7 params, no output schema, annotations present), this description is exceptionally complete. It covers purpose, usage, all parameter semantics, auth methods, billing behavior, and edge cases like the release_leases blind spot. The agent has everything needed to select and 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains the relationship between scope and resume_packet, the use case for disarm, the ordering and defaults of on_expiry, and the constraint that notify_address is required with queue_alert. This enrichment helps the agent use 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 clearly states the tool records a beat and arms a durable alarm for expect_within_seconds, using a specific verb (beat) and resource (dead-man switch). It distinguishes itself from siblings like lease_renew and work_done by focusing on external liveness detection, and explicitly references the release_leases and mark_failed paths as alternatives.

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

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

It explains when to call: periodically to signal liveness, and disarm when work finishes. It describes when on_expiry actions run and notes the blind spot of release_leases, providing clear context. However, it does not explicitly list exclusions or alternative tools for scenarios like simple completion, though the intent 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?

The description richly discloses behaviors beyond the annotations: idempotent double-ack, repeated-schedule queueing, tombstone result storage, redelivery handling without fence tokens, unknown-task returns, and FREE/no-charge. These add substantial context not present in the annotations, and there is no contradiction.

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

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

Though the description is long, every clause contributes critical operational detail. It front-loads the main action and then systematically covers idempotency, scheduling, redelivery, fencing, unknown tasks, cost, and authentication—no filler or repetition.

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

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

The description addresses all significant edge cases an agent would need: double-ack, repeated schedules, redelivery without fence tokens, unknown task_id, costing, and auth. Given the absence of an output schema, it also discloses the unknown-task return. This is a model of completeness.

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 describes all 4 parameters with 100% coverage, so the baseline is 3. The description adds extra value by explaining that the result object is stored on the tombstone, the status field is recorded but not interpreted, and agent_key is an alternative to the Authorization header, elevating it above the schema alone.

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

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

The description opens with 'Acknowledge a task you finished,' which clearly states the verb and resource. It distinguishes the tool from siblings by explicitly naming work_take/work_done as the fenced alternative and referencing inbox_poll for timeout adjustments, making the purpose unmistakable.

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

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

The description provides explicit usage guidance: 'Ack promptly, or raise visibility_timeout_seconds on inbox_poll' and 'if you need refuse-on-lost-ownership, that is work_take/work_done, which is fenced.' This directly tells the agent when to use this tool versus alternatives, satisfying the highest bar.

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 meaningful behavioral context beyond annotations by emphasizing that the operation is free, redelivery of the same task_id is free, and specifying authentication methods (Bearer header or agent_key argument). It also gives the equivalent HTTP route. These details are not present in the annotations, which only indicate idempotency and non-read-only, so the description enriches the agent's understanding without contradicting the annotations.

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

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

The description is fairly concise and front-loaded with the core purpose, but it repeats 'FREE' three times in two consecutive statements, which is redundant and undermines conciseness. The structure otherwise flows from purpose to cost to authentication to route, but the repetition wastes space.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers the essential aspects: purpose, optional deferral, cost behavior, authentication, and equivalent HTTP route. It does not describe error handling or response output, but with no output schema, return value details are not required. It is complete enough for an agent to select and invoke this tool correctly.

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

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

The input schema has 100% coverage with detailed per-parameter descriptions, so the baseline is 3. The tool description reiterates some param info (e.g., agent_key as a header alternative, delay_seconds for deferral) but does not add substantial new meaning beyond the schema descriptions. It effectively mirrors the schema rather than extending it.

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

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

Clearly states it 'explicitly return a claimed task to the queue instead of waiting for its visibility timeout, optionally deferring it.' The verb 'return' specifies the action on the resource, and it distinguishes from sibling tools like inbox_ack by framing it as a way to hand work back rather than completing or acknowledging it.

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

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

Provides a clear context: use when you want to return a claimed task instead of waiting for its timeout. Also mentions the optional delay for deferring. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' standard.

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

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

Annotations are minimal (all hints false), so the description carries the full burden of behavioral disclosure. It discloses the visibility timeout mechanism, redelivery behavior, cost structure (charged first delivery only), free redeliveries, zero charge when nothing is due, authentication methods, and the equivalent HTTP route. This goes far beyond what annotations provide.

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

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

The description is moderately long but every sentence earns its place; it covers purpose, behavior, cost, authentication, and routing without redundancy. The first sentence states the core function clearly, and subsequent sentences add necessary operational detail. It is well-structured and front-loaded with the most important 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, the description fully covers the call's behavior: what happens on success (delivered envelope), what happens on empty queue (explicit message and no charge), cost implications, authentication requirements, parameter purposes, and the relationship to ack/nack. Given the tool's complexity (polling, timeout, redelivery, billing), this is a complete and self-contained description.

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 with 100% coverage, so the baseline is 3. The description adds meaningful context: it explains when to use agent_key (if headers cannot be set), elaborates on visibility_timeout semantics (claimed item returns if not acked), and clarifies the mailbox concept. This provides real 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 opens with a specific verb and resource: "Collect the next due task envelope from your mailbox." It clearly specifies the action (poll for the next due task), the resource (mailbox/envelope), and the key constraint (one envelope per call). This distinguishes it from siblings like inbox_ack and inbox_nack, which handle acknowledgment, and work_take/claim, which are alternative work-retrieval mechanisms.

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

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

The description implies usage context: you poll to claim an envelope, then ack it when done, with a visibility timeout that returns it to the queue if not acked. It also states when nothing is due ("We say so and charge nothing"). However, it does not explicitly contrast with alternative tools like work_take or claim, nor does it say 'use this instead of X'. The guidance is clear but not exhaustive.

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 non-readonly and non-idempotent behavior, so the description carries the disclosure burden. It adds valuable context: the tool is FREE, requires authentication via Authorization header or agent_key, and maps to an HTTP route. It also clarifies that agents are not web services and that the message becomes available to inbox_poll on the next invocation.

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 well-structured: it opens with the core purpose, then clarifies delivery semantics, pricing, authentication, and the HTTP equivalent. The main redundancy is the repeated 'FREE' emphasis, but overall every sentence earns its place without bloating.

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

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

Given the tool's complexity (15 parameters, no output schema), the description covers the essential operational context: purpose, relationship to send and inbox_poll, authentication methods, and how the message will be received. It does not detail return values or complex parameter interactions, but those are largely self-documented in the schema.

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

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

All 15 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds marginal value by mentioning agent_key as an auth alternative and objective as the task content, but does not deeply elaborate on 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 clearly states the tool's purpose: 'Leave work for your own next invocation' — a specific verb (leave/schedule) and resource (future inbox). It distinguishes itself from siblings by noting it is 'the same as send() addressed to yourself' and that inbox_poll will retrieve the scheduled item.

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

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

The description gives clear context for when to use: to leave work for your own future invocation, and names send() as the comparable alternative. It also clarifies that no callback URL is required or accepted, implying webhook usage is not appropriate. It does not explicitly state when not to use, but the guidance is sufficient.

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 idempotent/destructive hints, description explains the cooperative stop mechanism (no kill), durability of flag, effect on work_take and should_continue, billing implications, and authentication methods. This is substantial context not available in annotations.

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

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

Description is dense with useful info but slightly repetitive (FREE mentioned twice) and has a few long sentences. It is front-loaded with the main purpose and includes necessary caveats, so it earns a strong 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 simple cancel tool with no output schema, the description covers purpose, side effects, related tools, auth, and HTTP route. No gaps remain for invocation decisions.

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 covers all 3 params, but description adds semantics: job_id aliases queue_id, reason is returned to workers, and agent_key is an alternative to the Authorization header. This adds value beyond schema field descriptions.

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

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

Title and description clearly state the tool cancels/stops a job by setting a durable stop flag, distinguishing it from individual task tools like work_fail or complete. The verb 'cancel' and resource 'job' are specific, and the description emphasizes its unique role among running agents.

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: use when you want to stop running agents, mentioning that there is no other way. It doesn't explicitly list alternatives or when-not-to-use, but references related behaviors of work_take and should_continue, giving enough 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 (readOnlyHint:false, idempotentHint:true, destructiveHint:false), the description adds crucial behavioral context: the fence is a credential, generation is an order counter, refusal is billed per holder, and the tool authenticates via Bearer header or agent_key. It also warns that acquired:null is not permission to proceed, which is not captured in any 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 long, but it front-loads the most critical warning ('ACQUIRED:FALSE MEANS YOU DO NOT HOLD THE LOCK') and every sentence carries significant information. There is slight repetition around not proceeding on refusal, but given the safety-critical nature, the extra length is justified.

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

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

The tool has no output schema, so the description carries the full burden of explaining return values; it does so thoroughly, covering acquired states, fence/generation, same_holder_label, held_by, and retry_after_seconds. It also addresses authentication, billing, edge cases (null state), and interaction with external stores.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains why holder must be unique per live instance, what scope does for recoverability, how fence functions as a credential for renewal, and how agent_key relates to Authorization. Each parameter's purpose and usage are greatly enriched.

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 'Mutual exclusion so two instances of the same agent do not both process one item', stating the exact purpose and resource. It explicitly describes the return states (acquired:true, acquired:false, acquired:null), distinguishing this lease-acquisition tool from sibling tools like lease_renew and lease_release.

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 explains when to use it (mutual exclusion) and what to do when acquired:false ('you must NOT proceed', 'wait retry_after_seconds'). It does not explicitly name alternatives like lease_renew or lease_release for renewal/release, but it does explain that renewal requires the fence, which implies the lease_renew 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 (destructive, idempotent), the description discloses refusal reasons ('released:false, reason not_holder'), that it names the current holder, that failed releases are not retryable, and that successful release corrects the scope ledger. It also states the tool is free and explains authentication options, adding substantial behavioral context.

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

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

The description is longer than the minimum, but every sentence adds value: purpose, failure modes, side effects, cost, and auth. It is front-loaded with the main action and efficiently packs necessary details, though it could be slightly trimmed without losing critical 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?

Despite having no output schema, the description covers the tool comprehensively: success behavior, failure reasons, treatment of stale/expired leases, side effects on the scope ledger, cost, authentication methods, and HTTP route. This is complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the fence semantics ('stale one is refused') and mentions agent_key as a fallback, but it does not add significant new parameter meaning beyond what the schema already documents.

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

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

The description uses a specific verb and resource: 'Release a lease you hold so the next worker can take it immediately instead of waiting for the TTL.' It clearly distinguishes this from sibling tools like lease (acquire) and lease_renew (extend) by focusing on the release action and its immediate effect.

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

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

It explains when to use the tool (when you hold a lease and want to hand it off), and gives explicit guidance on what happens in stale/expired cases ('Neither is an error you can retry away'). However, it does not explicitly mention alternatives like lease_renew for extending a lease, so it is not a full when/when-not comparison.

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

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

The description adds substantial behavioral context beyond the annotations: failure mode (renewed:false if lease expired/taken), preservation of fence and generation, side-effect on the scope ledger ('corrects the scope ledger, so resume_packet and the dead-man switch see the real new expiry'), cost (FREE), authentication method, and equivalent HTTP route. These are not present in the annotations and significantly help an agent understand side effects and failure handling.

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

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

The description is mostly efficient and front-loaded with the core purpose. Minor redundancy occurs with 'FREE' appearing twice and the sentence 'FREE — this tool never charges.' being repeated. However, given the complexity of the tool's behavior, each other sentence earns its place. The slight redundancy keeps it from a 5.

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

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

With no output schema, the description does well by mentioning the failure field (renewed:false), the side-effect on the ledger, and authentication. It does not describe the success response structure (e.g., new expiry value), but the description provides enough for an agent to understand the behavior and expected result. Slightly incomplete regarding return details.

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 extra meaning by clarifying the fence token is from lease() and unique per acquisition ('it is drawn independently for each acquisition, so it cannot be derived from an earlier one'), and that holder must be the same as originally used. It also explains the agent_key param context (when headers cannot be set). These additions go slightly 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 tool's function: 'Extend a lease you still hold, using the fence token you were given.' It uses a specific verb (extend) and resource (lease), and distinguishes itself from sibling tools like lease_release (ending a lease) and lease (acquiring a lease). No ambiguity about what this tool does.

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

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

The description gives clear context for when to use the tool: when you hold a lease and want to extend it. It also provides failure semantics ('Fails (renewed:false) if the lease expired or was taken by someone else — treat that as having lost the lock and stop work.'), which implicitly guides when not to proceed. It does not explicitly name alternatives, but the conditional and the 'same acquisition' wording make the use case clear.

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

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

Annotations only say the tool is not read-only and not idempotent, but the description goes far beyond: explains that the secret is never stored (salted SHA-256 digest), cannot be recovered, is the only credential, and is free. Warns that an amnesiac agent cannot remember it. These are valuable behavioral disclosures not inferable from annotations.

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

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

The description is detailed but every sentence conveys critical info (return values, security model, authentication, cost). It is front-loaded with the core verb. Minor redundancy via 'FREE' twice, but still appropriately sized for the complexity.

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

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

No output schema exists, so the description must explain return values, and it does: agent_secret, public agent address, and namespace id. It also covers authentication, persistence semantics, and cost. For a simple registration tool, this is fully self-contained.

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 already describes both parameters (100% coverage), but the description adds meaningful semantics: agent_id should never derive from provider session ids, agent_secret is optional with a minimum length, and aliases are noted. This supplements the schema with security-relevant guidance.

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

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

The description opens with a specific verb+resource: 'Create a durable identity for an agent.' It clearly distinguishes itself from siblings (e.g., whoami, send, work_*) by defining the registration role: returns credentials and namespace, not operational messaging or work tasks.

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

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

Provides explicit usage context: when to call (to create identity), how to authenticate afterward, and how to store the returned secret. Does not explicitly contrast with sibling tools, but the purpose is so distinct that exclusions are not necessary. Mentions alternative auth (agent_key as argument) and equivalent HTTP route.

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 (readOnly, idempotent, non-destructive), the description discloses substantial behavioral traits: the conditional billing model ('$0.002 only when... briefing has changed... otherwise free'), the use of server-observed facts, authentication requirements (Authorization header or agent_key argument), and the HTTP route. This goes well beyond the structured metadata.

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 typical but well-structured, front-loaded with the core purpose ('THE HEADLINE TOOL') and then progressing through contents, composition, provider-neutrality, pricing, authentication, and endpoint. Every sentence carries information, but some details (pricing breakdown) could be condensed 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?

Despite having no output schema, the description sufficiently documents what the response contains (briefing details, costs, empty scope behavior). It also covers critical operational aspects (billing, auth, server-side facts) that an agent needs to invoke and interpret results correctly. For the tool's complexity, the description is 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%, so baseline is 3. The description adds extra meaning for key parameters: it explains that an empty scope indicates no packet and costs nothing, and clarifies that agent_key is an alternative when headers cannot be set by the host. This enriches the schema descriptions without repeating them.

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

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

The description clearly states the tool's function: 'Returns a briefing, not an archive' and lists the specific contents (objective, last verified state, new events, next action, files, risks, etc.). It distinguishes itself from siblings by explaining it combines last checkpoint with server-observed facts, making it unique among tools like checkpoint_get 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 implies when to use it ('THE HEADLINE TOOL', 'Returns a briefing...') and clarifies it is more comprehensive than a raw checkpoint. However, it does not explicitly state when not to use it or name alternative tools for simpler needs (e.g., checkpoint_get for just the raw checkpoint). Clear context but no explicit 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?

Annotation Contradiction: The description states that record:true is a WRITE that counts a new attempt and produces a genuinely new answer, implying repeated calls with the same payload have different effects. This contradicts the annotation idempotentHint=true, which implies repeated identical calls are idempotent. Per the rubrics, any description that contradicts annotations receives a score of 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 description is overly long and repetitive, especially around billing. The $0.002 cost and when it applies is restated multiple times in different forms. While the core intent is front-loaded, the redundancies undermine conciseness and 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?

With no output schema, the description lists return values (attempt count, first/last times, suggested backoff) and explains authentication, billing, and the semantic distinction of record. It omits edge-case behavior like missing keys, but overall provides a robust operational picture 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?

Input schema coverage is 100%, so parameters are already well documented. The description adds billing semantics and clarifies record behavior, but mostly reiterates what the schema says (e.g., key hashing, record default false). It doesn't materially surpass the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies 'retry_state' as durable retry bookkeeping that survives crashes, and enumerates exactly what it returns (attempt count, first/last times, suggested backoff). It is distinct from sibling tools like work_fail or should_continue, which address different workflow concerns.

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

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

Provides explicit guidance: use record:true to count an attempt, record:false to read history without mutation. Also explains authentication options. It doesn't reference sibling tools as alternatives, but the usage context is clear enough for an agent to decide when to call this tool.

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

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

The description substantially exceeds annotations by disclosing that items are stored ONLY as salted SHA-256 digests, cannot be read/listed/reconstructed, sets max at 10,000 entries with refusal on overflow, and that the tool is FREE and requires authentication. These are key behavioral traits not present in annotations.

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

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

The description is compact and front-loaded with the primary purpose, but 'FREE' is repeated twice and the HTTP route is appended, adding minor redundancy. Overall it remains concise and readable.

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 write-only dedup tool, the description covers purpose, privacy, set limits, failure behavior, authentication, and cost. While no output schema exists and return values are not explicitly described, this is not critical for an add operation; the description is thorough and enables correct selection and 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?

Although schema coverage is 100%, the description adds meaningful constraints beyond the schema: set capacity of 10,000 entries and refusal when full, plus the privacy guarantee for items. It complements the schema's parameter descriptions without duplicating them.

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 'Record items you have already processed,' a specific verb+resource that clearly states the tool's function. It distinguishes from siblings like seen_check by focusing on adding/recording rather than checking, and clarifies storage as salted SHA-256 digests.

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

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

It explains when to use the tool: to record processed items, and provides explicit guidance on set rotation when full ('adds are refused... you should rotate to a new set name'). It does not explicitly name alternatives like seen_check, but the context implies the complement, and authentication instructions are given.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: exact billing conditions ('$0.002 ONLY when filtered_count >= 1...'), idempotency (same question free if set unchanged), authentication method, and HTTP route. This goes well beyond the annotations and fully discloses the cost and 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 contains redundant billing explanations (e.g., '$0.002 ONLY when we filter...' and 'Costs $0.002 USDC per call... ONLY when filtered_count >= 1'). While informative, the repetition wastes space. The core purpose is front-loaded, but the duplication and long billing segment make it less concise than it could be.

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?

There is no output schema, so the description carries the responsibility of explaining return values. It states that the tool returns only the new items and says 'If every item is new we tell you so,' covering the main behavior. It also covers auth, billing, and route. It lacks an exact response shape, but for a simple filtered-list tool, the provided description is sufficiently 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%, and the schema already describes each parameter (set, items, agent_key) with examples. The description mentions agent_key in the authentication context and references the set name implicitly ('this exact set of already-seen items'), but it does not add new semantic meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Given a batch of items, return only the ones not already in the set — the work you actually still have to do.' This is a specific verb (return) plus resource (items not in set), and it distinguishes the check operation from the sibling tool seen_add, which would add items.

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

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

The description provides clear context for when to use the tool ('the work you actually still have to do'), implying it's used to filter out already-seen items before processing. It also explains billing conditions that affect usage, such as when calls are free. However, it does not explicitly name alternatives like seen_add.

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

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

With all annotations false (readOnlyHint, idempotentHint, destructiveHint), the description carries the burden of disclosing effects, and it does so substantially. It states the tool never charges ('FREE'), queues rather than delivers synchronously, respects mailbox capacity limits ('968 ordinary items + 32 reserved for safety alerts'), and guarantees safety notifications cannot be silenced by flooding. It also discloses authentication requirements (Bearer header or agent_key). This goes well 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 a clear purpose statement and then expands into relevant details. It is efficient but has minor redundancy: 'FREE.' appears twice ('FREE.' and 'FREE — this tool never charges.'). It is longer than strictly necessary but every other sentence earns its place, covering safety, capacity, and authentication.

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 tool with 15 parameters, no output schema, and all-false annotations, the description is remarkably complete. It covers the core behavior, cost model, capacity limits, safety guarantees, and authentication. The only notable omission is the return value or outcome of a successful send (e.g., whether it returns a message ID or ack), which would help since there is no output schema. Still, the description gives the agent enough to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 15 parameters, so the baseline is 3. The description adds extra meaning by explaining the envelope's purpose: 'The envelope carries objective, context, attachments and history so the receiving invocation can start work without rebuilding state it no longer has.' This gives semantic rationale for several parameters that the schema alone does not convey. It doesn't cover every parameter, but the schema already does that, so 4 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 opens with 'Agent-to-agent mail' and immediately defines the action: 'Queue a rich task envelope addressed to any registered agent.' This names the verb (queue/send), the resource (task envelope), and the delivery model (asynchronous mailbox), clearly distinguishing it from sibling tools like inbox_poll or work_push. It also explicitly states what the tool does NOT do: 'You may SEND to an address but never READ another agent's mailbox.'

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 send: when you need to deliver work to another agent asynchronously, with 'Nobody waits and nobody polls.' It also provides a usage exclusion: 'You may SEND to an address but never READ another agent's mailbox — reading requires that agent's secret.' However, it does not explicitly name alternative tools (like inbox_poll or inbox_ack) as the rubric's top tier requires, so it falls short of a 5.

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

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

The description thoroughly discloses billing behavior (only charged on false, free on true), unknown-job handling, fail-closed null semantics, retry advice, authentication methods, and the HTTP route. This goes far beyond the annotations and adds valuable context about side effects and failure modes.

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

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

The description is a single dense paragraph with redundant cost explanations: '$0.002 ONLY WHEN THE ANSWER IS no', 'FREE, always', and 'Costs $0.002 USDC per call...' repeat the same billing point. While information-dense, the lack of structure and repetition make it harder to parse quickly.

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 no output schema, the description covers auth, billing, failure semantics, and route. However, it never explicitly states the response shape (e.g., an object with a `continue` boolean/null), instead implying it via 'continue:null' and 'continue === false'. The full return contract remains somewhat vague.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by noting the job_id alias 'queue_id', providing an example, clarifying agent_key is a fallback when headers cannot be set, and explaining the behavioral effect of unknown job IDs. This exceeds baseline.

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

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

The description positions this as 'the check a worker makes between items,' and the title 'Should I keep going' reinforces that it asks whether a job should continue. However, it never directly states 'returns whether the job should continue' or explicitly names the boolean response field, so the purpose is clear but slightly implicit.

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

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

It gives clear usage context: this is a per-item check, and when state cannot be determined it says to 'retry rather than guess.' It also explains unknown jobs behave as 'keep going.' It does not name sibling alternatives, but the context is specific enough that an agent would know when to call 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 provide readOnly/idempotent hints, but the description adds significant context: the billing model (cost only when position has moved and not previously billed), free re-reads, and auth requirements (Authorization header or agent_key). This goes well beyond the annotations and clarifies real-world 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 somewhat long and contains redundancy: the billing rule is explained twice ('$0.002 ONLY when...' and 'Costs $0.002... ONLY when found === true'). While each piece of info is useful, the repetition could be tightened, making it less concise than ideal.

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

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

For a tool with billing and auth complexity, the description covers most key aspects (cost conditions, no-watermark case, auth, HTTP route). However, it does not describe the return structure (e.g., what 'found === true' implies for the response), which would be valuable given the lack of 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%, but the description adds meaningful nuance for agent_key (when to use it, preference for header) and stream (example). This enriches the parameters without being redundant.

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

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

The description clearly states the tool fetches the last recorded position for a stream, with a specific verb ('Fetch') and resource. It distinguishes itself from siblings like watermark_set by focusing on retrieval, and the purpose ('ask an upstream only for what is new') adds context.

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

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

The description implies when to use it (after a watermark has been set, to check for new data) and mentions behavior when no watermark exists. However, it does not explicitly name alternatives or state when not to use it, so it stops short of providing full usage guidance.

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

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

The description adds context beyond the annotations: the position is 'an opaque string we store verbatim and never interpret,' the tool is free, and authentication can be done via Authorization header or agent_key argument. These behavioral details are not present in the readOnlyHint/idempotentHint/destructiveHint annotations, enriching agent understanding of side effects and invocation constraints.

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 concise (four sentences) and front-loads the primary purpose. However, FREE is stated twice ('FREE.' and 'FREE — this tool never charges.'), which is redundant and slightly violates the 'every sentence earns its place' principle. Otherwise, the structure is clear and efficient.

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

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

For a simple write tool with no output schema, the description adequately covers the core behavior, auth, HTTP route, and opaque position handling. It does not explicitly state overwrite behavior (e.g., calling it again replaces the prior position), but the term 'record' implies this. Overall, it is sufficiently complete for an agent to select and use the tool correctly.

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

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

Schema description coverage is 100%, so all five parameters already have detailed meanings. The description reiterates that position is 'opaque' (already in the schema) and mentions agent_key as an alternative authentication method (also in the schema), adding no new param semantics beyond what the input schema provides. Thus 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 begins with a specific verb-resource pair: 'Record how far you got through a stream, feed or table,' making the tool's function unmistakable. It also differentiates from siblings like watermark_get by focusing on writing progress, and the phrase 'so the next invocation knows where to start' clarifies the downstream 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 clearly conveys the use case—recording progress through a stream, feed, or table—and implies it should be called after consuming data. However, it does not explicitly name alternatives or explain when not to use this tool (e.g., for ephemeral checkpoints use checkpoint_put), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: the tool is intentionally free and never charges, and it requires authentication via a header or agent_key. This helps the agent understand cost and auth implications.

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 purpose, but the emphasis on 'FREE' is repeated four times across multiple sentences, which is redundant. The auth and HTTP route information is useful, but the cost messaging could be condensed 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 effectively enumerates the response contents: public address, registration time, mailbox counts, due now, next due, and dead-lettered counts. It also covers authentication and cost behavior, making it sufficiently complete for a simple read-only status 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% with a single optional parameter (agent_key). The description's mention of agent_key as an authentication alternative mirrors the schema, adding no new semantic meaning beyond what the schema already provides. Baseline of 3 applies.

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

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

The description clearly states the tool's purpose with a specific verb ('Report') and resource ('this namespace's public address, registration time, and mailbox counts'), and enumerates the exact details returned. This distinguishes it from sibling tools like inbox_poll or work_take, which are action-oriented.

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

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

The description provides clear usage context: 'Poll this for free, then pay only when there is something to collect.' This implies when this tool should be used (free status checking) and clarifies there is no cost. It does not explicitly name alternative tools, but the guidance 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?

The description goes well beyond annotations, explaining the lease_lost and fence_required refusal cases, the opaque and never-parsed nature of the result, how the result surfaces via work_status, the cost (FREE), and authentication requirements. This provides extensive behavioral context for a mutation/destructive tool.

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

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

The description is a single dense paragraph that repeats 'FREE' twice and includes an HTTP route, which is not essential for MCP invocation. It front-loads the main purpose well but could be tightened without losing key safety and refusal details.

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

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

For a complex mutation with no output schema, the description covers when to use, error conditions, result behavior, authentication, and cost. It does not specify what the direct response from work_done is on success, but given the rich context and idempotent annotation, it is largely 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?

While the schema already documents all 5 parameters with 100% coverage, the description adds critical semantic context for fence (why it exists, what happens without it) and result (opaque, returned via work_status). This raises the value beyond the schema's plain definitions.

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 'Complete an item you hold,' which clearly states the action and target. It further clarifies that this is for finishing a work item successfully, and distinguishes itself from work_fail by noting identical refusal behavior for fence-less calls, implying the success/failure split.

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 states when to use (when you hold the item and want to mark it done) and describes failure conditions (lease expired, fence token mismatches). It references work_fail for comparison but does not explicitly say 'use work_fail for failures,' so it lacks a direct alternative recommendation.

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

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

Beyond the annotations (readOnlyHint:false, destructiveHint:true), the description details critical behaviors: attempts exhaustion leads to dead-lettering and surfacing in work_status, never silently dropped; retry:false cannot be undone; and fence validation failures (lease_lost, not_holder, fence_required) with the safety rationale. It also discloses the tool is free, requires auth, and has an HTTP route, adding depth beyond structured metadata.

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 information-dense and front-loaded with the main purpose and the surprising hand-back use case. However, it contains redundancy—'FREE' appears twice, and 'this tool never charges' repeats the point—and the fence explanation is lengthy, though necessary. Overall it is reasonably structured but not perfectly concise.

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

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

Despite having no output schema, the description covers the full behavioral spectrum: success and failure modes, dead-lettering, fence edge cases, error codes, authentication, and the HTTP equivalent. This is a complex tool, and the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, establishing a baseline of 3. The description enhances retry semantics (immediate return instead of waiting out the lease) and fence semantics (failure codes and the rationale for refusing stale/fenceless calls), though other parameters rely on their 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 tool's role as reporting a work item that did not work out, but also reveals it is the correct way to hand back an item when nothing went wrong, explicitly noting there is no work_release. It distinguishes from siblings by referencing work_done and work_status, making the purpose 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 provides explicit when-to-use guidance: use retry:true to immediately return an item for another worker (since there is no work_release), and retry:false to permanently fail it. It also warns about fence behavior matching work_done, giving a clear alternative for successful completion.

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, disclosing idempotency (per item_id), opaque payloads, free usage, authentication methods, HTTP route, and queue lifetime limits. It aligns with idempotentHint=true and readOnlyHint=false, with no contradiction.

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 somewhat verbose, with dramatic capitalization and repeated mention of 'FREE' twice. However, it is front-loaded with the core alternative and packs in critical details, making it long but not without purpose.

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

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

Given the lack of an output schema, the description explains what happens on push (queue holds items, workers pull), failure modes (refused when over limit), and operational specifics (auth, HTTP route). It is thorough, though it omits the exact success response format.

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?

Even though schema coverage is 100%, the description adds meaning to parameters by explaining idempotency semantics for items, namespace-scoping for queue_id, and authentication alternatives. This enriches the schema without being redundant.

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

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

The title and description clearly state the tool pushes work items onto a durable queue. The description specifies the action ('Push 100 items in one go and exit') and contrasts with alternative approaches, distinguishing it from sibling tools like work_take.

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

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

The description provides clear usage context: it is for enqueueing work without building custom distribution, with batching and idempotency advice. It does not explicitly mention sibling tools for pulling or processing, but the contrast with writing your own system gives strong when-to-use guidance.

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

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

The description discloses critical behavioral details beyond annotations: billing occurs only when there is real progress and the state changed, counts are exact (scanned, not drifted), arrays are windowed at 50 rows with page tokens, paging is free, and authentication methods. This is far more than the idempotentHint/readOnlyHint annotations provide, with no contradictions.

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 adds unique value: purpose, use case, counting method, cost model, pagination, and auth. It is front-loaded with the core purpose and then details. While long, the all-caps emphasis and multiple clauses make it slightly harder to scan, but it remains appropriately sized for the tool's complexity.

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

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

With no output schema, the description must describe the return shape, and it does: counts, collected results, dead letters with errors, and page tokens. It also covers cost, idempotency, auth, and the equivalent HTTP route. For a tool with billing and pagination nuances, this is comprehensive and leaves no essential behavior unexplained.

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 description does not need to define basic parameters. It adds meaning beyond the schema by explaining that page tokens enable access to windowed arrays, that paging is free, and how agent_key relates to the Authorization header. This contextualizes the parameters' purpose and 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 clearly states the tool's function: turning a fan-out from a black box into something actionable by reporting counts (pending, leased, done, failed, dead-lettered), results, and dead letters. It uses a specific verb ('turn... into') and resource (fan-out progress), and the use case (proceeding with 4 of 5) differentiates 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?

The description explicitly identifies when to use this tool: when a parent needs to decide whether to proceed with partial completions instead of blocking on a straggler. It provides context for use but does not explicitly name alternatives or state when not to use it, relying on the clear scenario to imply usage.

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 covers critical behaviors beyond the annotations: leases expire and items return, fence tokens are independent, generation equals attempts, empty queues return nothing, and pricing only applies on first-time handouts. It also details authentication methods and the equivalent HTTP route — all valuable context that annotations (all false) 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 a single, extremely long paragraph with repeated pricing information and all-caps emphasis. It lacks bullet points or structured sections, making it harder to parse quickly. Several sentences could be merged or removed without losing value, so it fails the 'every sentence earns its place' test.

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 thoroughly explains what happens on success, on empty/cancelled queues, and on re-takes after lease expiry. It also covers pricing, authentication, and the HTTP route, making the tool fully self-contained for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds background on lease semantics and examples (e.g., n up to 25, lease_seconds defaults), but it does not go beyond the parameter-level details already present in the schema. It therefore meets the baseline without meaningful enrichment.

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 'Take up to n items, LEASED not deleted' — a specific verb, resource, and lease semantics that clearly distinguish it from sibling lease management tools. It also explicitly contrasts with lease()/renew()/release() and mentions the same behavior, leaving no ambiguity about what work_take does.

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

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

The description explains when items return to the queue (lease expiry) and what happens on empty/cancelled queues, giving clear operational context. However, it does not explicitly name alternative tools like work_done or work_fail for when NOT to use this tool, so the guidance stays implied rather than explicitly exclusions.

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