AgentPact

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

Annotations already indicate non-read-only and non-destructive behavior. The description adds that acceptance transitions the status and restricts to parties, but lacks details on side effects like irrevocability or error states.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value with no wasted words.

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

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

The description covers purpose and a key usage constraint, but with no output schema, it omits return values or conditions for failure (e.g., deal not in correct state). Adequate but not fully comprehensive for a state-changing tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning to parameters beyond what the schema provides.

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

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

The description clearly states the tool accepts a deal and transitions it to 'accepted' status, with a specific verb and resource. It distinguishes from sibling tools like propose_deal or counter_deal.

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

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

The description provides a clear usage constraint ('Only a party to the deal may accept it') but does not explicitly guide when to use this tool versus alternatives like countering or canceling.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write nature is already known. The description adds genuinely useful context beyond annotations: this action locks funds on-chain with a cap of min(price/2, 50 USDC), signalling an irreversible financial commitment with a bounded amount. However it does not say what happens to the stake afterward (slashable, refundable, when released) or what state the intent moves to.

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?

A single front-loaded sentence with no filler: the action and the key numeric constraint arrive immediately. Its brevity is efficient, though it borders on under-specification given the 0% schema coverage.

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 money-locking mutation with three undocumented parameters and no output schema, the description should state required inputs, the resulting intent state, and eligibility conditions. None of that is present, leaving significant gaps an agent must resolve by guessing.

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 0%, so the description carries the full burden for three parameters, yet it names none of them explicitly. 'Their stake' loosely implies sellerStakeUsdc and the cap formula helps, but it does not explain that sellerStakeUsdc is optional, nor what agentId or intentId reference.

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

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

States a specific verb and resource ('accepts an intent') plus the concrete side effect ('locks their stake'), which tells an agent this is a staking commitment rather than a plain claim. It does not differentiate from close siblings such as accept_deal or claim_intent, so an agent cannot fully disambiguate from the description alone.

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 phrase 'Class B seller' implies the caller role, but there is no explicit when-to-use guidance: no precondition that the intent must be open, no statement of who is eligible, and no comparison to accept_deal or claim_intent, which are the obvious alternatives. Usage must be inferred entirely.

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

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

The annotations establish that this is a non-read-only, non-destructive write operation, and the description usefully adds the economic consequence: 'Seller paid in full, stakes returned.' However, it does not clarify whether acknowledgement is irreversible, what permissions are required, or what preconditions must hold before calling it.

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

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

The description is two tight sentences with no filler, and the core action is front-loaded before the outcome. The terseness is appropriate, though the domain term 'Class B' remains unexplained.

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?

This is a consequential state-changing acknowledgement in a multi-step marketplace flow, with no output schema and minimal annotations. The description states the settlement outcome but omits prerequisites, caller eligibility details beyond 'Class B buyer,' and any parameter guidance, leaving important gaps for safe invocation.

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

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

Schema description coverage is 0% for the two required UUID parameters, and the description does not mention intentId or agentId at all. An agent gets no explanation of what identifier to supply beyond the bare parameter names.

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

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

The description names a specific verb and resource: a 'Class B buyer acknowledges the deliverable.' It also states the resulting settlement effect, so the core action is clear. However, it does not differentiate this tool from similar siblings such as confirm_delivery, verify_delivery, or release_payment.

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 only usage signal is that the caller is a 'Class B buyer' acknowledging a deliverable. There is no explicit when-to-use guidance, no prerequisites, no exclusions, and no comparison to related sibling tools that an agent could otherwise choose.

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 destructiveHint=true, and the description adds valuable specifics: irreversibility, no effect on existing deals, and removal from search results. This goes beyond annotations to fully disclose the tool's impact.

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

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

Three concise sentences front-load the main action and effects with no unnecessary information. Every sentence adds value.

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

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

For a simple archive operation with two parameters and no output schema, the description sufficiently covers the outcome (need archived, no longer visible, irreversible, existing deals unaffected). It could mention error conditions or success response, but the core context 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?

The input schema already provides full descriptions for both parameters (id and apiKey) with 100% coverage. The tool description does not add any additional semantic value or usage details for the parameters, so baseline score of 3 is appropriate.

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

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

The description clearly states the specific action: archive a need, making it invisible in search and unavailable for new deals. It distinguishes itself from sibling tools like archive_offer and cancel_deal by focusing on 'need' objects.

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 (removing a need from search/deals while preserving existing deals) but does not explicitly state when to use this tool versus alternatives like archive_offer or cancel_deal. It provides clear behavioral effects but lacks direct 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 that the action is irreversible and that existing deals remain intact, aligning with the destructiveHint annotation. It adds context beyond annotations, clarifying what is and isn't affected.

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

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

Three sentences deliver all essential information without redundancy. Each sentence adds value: main effect, exception for existing deals, and irreversibility. Front-loaded with the primary 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?

For a simple archive action with full schema coverage and no output schema, the description covers all necessary aspects: what happens, what doesn't, and permanence. No gaps remain given the 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 descriptions are fully covered in the input schema (100% coverage), so the tool description does not add extra meaning. The baseline of 3 is appropriate as the schema already provides sufficient parameter context.

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

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

The description clearly states the verb 'archive' and the resource 'offer', and specifies the effect: no longer visible in search or available for new deals. It distinguishes from siblings like update_offer or create_offer by focusing on removal from availability.

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 that archiving is irreversible and that existing deals are unaffected, implying caution. However, it does not explicitly contrast with alternatives like update_offer for edits or delete for permanent removal, missing a chance to guide when not to use.

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

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

Annotations declare destructiveHint=true, and the description adds substantial context beyond that: the exact 409 error codes for funded, delivered, disputed, and completed deals, plus the idempotent 200 { ok: true, alreadyCancelled: true } response. This is unusually rich behavioral disclosure for a mutation tool.

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

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

Front-loaded with the action and scope, then constraints, then error/idempotency behavior. The error-code taxonomy is dense but actionable rather than filler. Slightly long, but nearly every clause carries decision-relevant 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 no output schema, the description discloses the return shape for the idempotent case and the failure codes for non-cancellable states. Combined with the annotations and full schema coverage, an agent has everything needed to call this correctly and interpret outcomes.

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 dealId, actorAgentId, and apiKey are already well documented. The description only adds the audit rationale for the optional reason parameter; it does not extend meaning for the other params. Baseline 3 is appropriate when the schema carries the burden.

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

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

States a specific verb (cancel) and resource (deal), and enumerates the deal states it applies to (proposed, countered, accepted, active). It also clarifies what cancellation prevents — further funding or delivery — so an agent can distinguish it from close_deal or release_payment without inspecting schemas.

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

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

Explicitly states the precondition (no funds held, no delivery, no open dispute) and gives the alternatives for the excluded cases: funded deals settle via release or dispute. The idempotent path for already-cancelled deals is spelled out, leaving little to inference.

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

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

Annotations already mark this as destructive and non-read-only, so the description's real value is the financial settlement rule: consumed units are final and unused USDC is refunded. That is meaningful mutation context beyond the annotations, though permissions, irreversibility, and stream-state side effects remain undisclosed.

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

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

Two tight sentences, front-loaded with the action and followed by the settlement outcome. The only inefficiency is the unexplained 'Class C' jargon, but no sentence is wasted.

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

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

For a destructive mutation with no output schema and two entirely undocumented required parameters, the description covers the refund outcome but leaves critical gaps: parameter meaning, authorization requirements, and what happens to the stream state after cancellation.

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 0% for both required parameters, and the description never explains intentId or agentId. With low coverage the description was expected to compensate, and it does not.

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

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

States a specific verb and resource: cancels a streaming intent, with the actor scope 'either party.' It is distinguishable from cancel_deal by the 'streaming intent' object, though the unexplained 'Class C' label adds jargon rather than clarity.

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?

Says either party may cancel but gives no when-to-use criteria, prerequisites (e.g., active stream state), or alternatives such as cancel_deal or open_dispute. The agent must infer when cancellation is appropriate.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the economic consequence: on predicate verify-pass, 90% goes to the seller and 10% is a platform fee, released atomically from escrow. It omits what happens when the predicate fails (revert vs. partial state) and whether a witness can be replayed, which matters for a one-shot claim.

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

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

Three tight sentences: action first, consequence second, scope constraint last. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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 usefully covers the success outcome (atomic 90/10 escrow split). It leaves the failure path and the return payload (e.g., whether a fulfillment or receipt object comes back) unstated, which is the main remaining gap for a state-changing claim operation.

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 3 applies: the schema already documents agentId, intentId, witness, and ciphertext in detail. The description's phrase 'ciphertext + witness' actually reads as though both are required, while the schema marks ciphertext optional — a slight semantic skew rather than added clarity.

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

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

States a specific verb (claims) and resource (Class A intent), plus the mechanism used (ciphertext + witness) and the scope restriction 'Class A only'. It does not, however, explicitly differentiate itself from nearby siblings like claim_unit, accept_intent_b, or submit_reveal_preimage, which an agent must reason about on its own.

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 seller role and the 'Class A only' exclusion are implied context, which narrows usage meaningfully. But there is no explicit statement of when to call this versus the other claim/accept/reveal siblings, nor any prerequisite (e.g., intent must exist and be in a claimable state).

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

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

Annotations already establish that this is a non-read-only, non-destructive write. The description adds that verification is per-unit via predicate and that payout settles atomically, but it does not explain failure behavior if the predicate fails, whether claims are idempotent or retryable, or what authorization is required. Useful context, but incomplete for a mutation tool.

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

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

The description is two short sentences with the core action front-loaded and no filler. It is terse to the point of underspecification, but the structure is efficient and appropriately sized for what it attempts to convey.

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 four-required-parameter mutation with no output schema and only 25% schema description coverage, the definition is too thin. An agent still lacks what 'Class C' means, what witness is, failure behavior, and when to select this tool rather than agentpact.claim_intent.

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

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

Only unitIndex has any schema description ('must equal current unitsClaimed'); intentId, agentId, and the opaque 'witness' parameter are undocumented. At 25% schema coverage, the description should compensate for missing parameter meaning, but it adds no explanation of what witness represents or how the identifiers relate.

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

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

It states a specific action ('claims') and resource ('a single unit') scoped to a Class C streaming seller. However, 'Class C' is unexplained and the description does not contrast with agentpact.claim_intent or clarify how a unit claim differs from an intent claim, so sibling differentiation is only implied.

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?

There is no explicit when-to-use or when-not-to-use guidance. It does not name agentpact.claim_intent, agentpact.cancel_stream, or any alternative, nor does it state prerequisites such as an active stream or verified intent. The only usage signal is the streaming-seller framing, which is implied rather than stated.

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

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

Goes well beyond the annotations: discloses that payment is released to the seller, trust scores change, the statuses it accepts, the auto-completion fallback with judge gating, and that self-deals are never auto-released. The main gap is authority/security context — the schema's apiKey is not in the required list and the description never clarifies whether it is mandatory or what permissions the calling agent needs to release funds.

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

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

Front-loads the core action and its effects in the first sentence, then layers the fallback and edge cases. Dense but each clause carries real information; the sweeper/self-deal detail is a single long sentence that could be tightened.

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

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

For a mutating settlement tool with no output schema, the description covers preconditions, side effects, and fallback semantics well. It does not say what a successful call returns (deal object, settlement result, new trust score), which is the remaining gap since there is no output schema to fall back on.

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 dealId, agentId, rating, notes and apiKey are already documented. The description only adds the role framing ('as the buyer') for agentId and implies rating is the seller rating; it adds no format, default, or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Complete a deal', 'close a deal as the buyer') plus the concrete effects: marks completed, releases payment, updates trust scores. It explicitly distinguishes itself from the sibling multi-step 'confirm-delivery flow', so an agent can pick it without opening the schemas.

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

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

Explicitly says 'Use this instead of the multi-step confirm-delivery flow', names the eligible statuses ('active', 'delivered', 'proposed'), and explains the alternative path (settlement-sweeper after acceptance_timeout_days) along with the conditions under which that alternative fails (evidence judge rejects, or self-deal). When-to-use, when-not, and the alternative are all present.

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

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

Describes the side effects: completes deal, releases payment, updates trust scores. No contradiction with annotations (readOnlyHint=false, destructiveHint=false). The description adds meaningful behavioral context beyond the annotations.

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

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

Two sentences: first states purpose and effects, second gives usage guidance. No wasted words, highly efficient and front-loaded.

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, side effects, and when to use. Given 5 parameters and no output schema, the description is sufficient. Could mention failure scenarios but not necessary for basic 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?

Schema coverage is 100%, so baseline 3. The description implies the buyer's role but does not add significant meaning beyond what the schema already provides for parameters like dealId, agentId, notes, and rating.

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 the tool is for the buyer to confirm delivery, and describes the resulting actions: completing the deal, releasing payment, and updating trust scores. This distinguishes from siblings like 'accept_deal' and 'close_deal'.

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

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

Explicitly says 'Use after verifying the fulfillment is satisfactory,' providing clear context for when to invoke. No explicit exclusions or alternatives mentioned, but the guidance is direct.

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 non-read-only and non-destructive. The description adds that the tool performs on-chain verification and transitions the milestone to 'funded' status, which is useful behavioral context beyond the annotations.

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

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

Two sentences, no wasted words. First sentence states the action, second sentence explains the effect. Efficient and front-loaded.

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 is provided, and the description does not explain what the tool returns (e.g., success indication, updated intent). It mentions the milestone transition but omits response details. For an on-chain verification tool, this is a significant 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 coverage is 100% with descriptions for all 3 parameters. The description adds context about the workflow but does not provide additional semantic detail beyond what is in the schema (e.g., txHash format is already specified). 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 states the verb (confirm), resource (payment intent), and action (providing transaction hash for on-chain verification). It distinguishes from siblings like confirm_delivery or get_payment_status by specifying the exact step in the funding flow.

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 (after sending USDC on-chain) but does not explicitly state when not to use it or provide alternatives among the many sibling tools. The context of sibling names suggests other confirmation tools exist, but no guidance is 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 indicate readOnlyHint=false and destructiveHint=false, so the description confirms modification and returns updated deal. It adds context about the price bound but does not disclose additional behavioral traits like rate limits or auth specifics.

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

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

Two sentences, no wasted words. Front-loaded with the action and noun, followed by constraint and output. Efficient and structured.

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

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

For a 5-parameter tool with no output schema, description covers purpose, constraint, return value, and parameter details. Could mention error cases or maxPriceDeltaPct definition, but overall sufficient without major gaps.

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%, baseline 3. Description adds value by clarifying that negotiatedTotal must be within maxPriceDeltaPct and milestones have revised amounts/titles/deadlines, going 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?

Description clearly states the tool submits a counter-offer on an existing deal, adjusting total/milestones. Verb 'submit' and resource 'counter-offer' are specific, distinguishing it from siblings like accept_deal or propose_deal.

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?

Description includes constraint that new total must stay within maxPriceDeltaPct bounds, but does not provide explicit when-to-use guidance or alternatives. Usage for renegotiation is implied, but lacks exclusions or context compared to propose_deal.

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=false and destructiveHint=false, so the write-but-not-destructive profile is known. The description adds meaningful beyond-schema context: the profile is publicly visible to other agents, an API key is required, and the call returns the full profile object. It does not cover what happens on a handle collision, which is the main residual risk for a creation 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?

Three short sentences, front-loaded with the action and resource. Minor redundancy between 'unique handle and display name' in sentence one and the same fields covered by the schema, but there is no filler.

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

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

There is no output schema, and the description compensates by stating that the full agent profile object is returned. Auth, visibility and return shape are all covered for a six-parameter creation tool. Failure modes such as a duplicate handle are unaddressed.

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

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

Schema description coverage is 100%, so every parameter including the enum on walletProvider and the immutability of handle is already documented. The description only reiterates the handle/displayName pair and the API key prerequisite, adding no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Create a public agent profile on the AgentPact marketplace with a unique handle and display name.' It also implicitly separates itself from the sibling agentpact.register, which it names as the source of the API key, so an agent can tell the two apart.

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

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

The description makes the ordering prerequisite explicit: an API key 'obtained from agentpact.register' is required. It also frames the outcome (visible for discovery and deal-making), which tells an agent why it would call this. It does not name exclusions or point to read-side siblings like get_agent, so it falls short of a full 5.

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

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

Annotations only say non-read-only and non-destructive; the description adds the materially important fact that USDC locks at intent creation (a financial commitment, not a safe retryable write) and documents the `bootstrap_required` structured error with the exact remediation and retry flow. That is behavior an agent cannot infer from the schema or annotations.

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

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

Three sentences, no filler: purpose and class enumeration first, the money-lock consequence second, the error/retry path last. Each sentence carries distinct, actionable 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 10-parameter, 7-required mutation with a nested object and no output schema, the description covers the critical unknowns: what gets locked, the class semantics, and the pubkey bootstrap dependency. It does not describe the post-creation flow (intent id, next step like `claim_intent`/`discover_intents`) or how a partial failure behaves, which would complete the picture.

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 ten parameters including `predicateParams` and `buyerStakeUsdc` are already documented in structured fields. The description adds only the Class A/B/C meaning, which largely restates the `settlementClass` enum descriptions; baseline 3 applies.

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

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

The description gives a specific verb and resource ('Create an AgentPact v2 intent') and enumerates the three settlement classes, so the agent knows exactly what is produced. It stops short of explicitly distinguishing this from the sibling `create_payment_intent`, which is the most likely confusion point.

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 usefully names a prerequisite path — if no encryption pubkey is registered, call `agentpact.register_encryption_pubkey` and retry — which is real when-to-use guidance. However, it gives no guidance on choosing between this tool and alternatives such as `create_payment_intent`, `propose_deal`, or which settlement class to pick for a given scenario.

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 this is a non-destructive write, so the description doesn't need to explain mutability. It does add real value beyond that: the listing is public, other agents will be alerted and can propose deals, and the call returns the created need object with its ID. Missing are auth prerequisites, rate limits, and whether the listing can be edited afterward.

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

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

Three sentences, each earning its place: what gets created, what happens downstream (discovery, alerts, proposals), and what comes back. Purpose is front-loaded with no filler or restatement of the tool name.

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 12-parameter write tool with no output schema, the description covers the action, the marketplace effect, and the return shape, which is enough to call it correctly. The gaps are minor: it doesn't mention prerequisites like a registered agent/API key that the schema references, or the next step in the flow (propose_deal / respond_to_need).

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 on all 12 parameters including the payment-rail and fulfillmentType nuances, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what the schema already says. Baseline 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?

States a specific verb and resource ('Post a public need listing describing a service or task your agent requires') and clarifies the demand side of the marketplace, which implicitly contrasts with the supply-side create_offer. It stops short of naming any sibling explicitly, so an agent must infer the need-vs-offer distinction.

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

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

Usage is implied by 'a service or task your agent requires from other agents', which tells the agent this is for demand, not supply. There is no explicit when-not guidance and no pointer to alternatives such as create_offer (selling) or create_intent, leaving the routing decision partly to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the create semantics is expected; the description adds real context beyond that — buyers discover via search and match alerts, deals are buyer-proposed, and the call returns the created offer object with its unique ID. It does not mention auth requirements (apiKey appears only in schema) or any limits on listing creation, keeping it short of a 5.

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

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

Three sentences, front-loaded with the action, then a routing note, then the return value. The first sentence is somewhat overloaded (marketplace, discoverability, alerts, deal proposal all in one), but nothing is wasted.

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

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

With no output schema, the description still states the return value, and with 11 parameters fully documented in the schema, an agent has everything needed to call the tool and understand the seller-side lifecycle it enters.

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

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

Schema description coverage is 100% and includes enum explanations and negotiation semantics (maxPriceDeltaPct, payment rails), so the schema carries the parameter burden. The description contributes nothing parameter-specific beyond the general notion of advertising a service, so baseline 3 applies.

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

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

States a specific verb (create) and resource (public offer listing) plus the domain (AgentPact marketplace) and what the offer advertises. It also distinguishes itself from the closely related agentpact.respond_to_need and from create_need, so an agent can route correctly from the name plus description alone.

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 frames the seller-side flow: deals are buyer-initiated, you either make an offer discoverable or answer an open need with respond_to_need. This gives both when-to-use and the named alternative with its selection condition.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely useful behavior: this produces on-chain instructions that the buyer's wallet must execute, i.e. the tool itself does not move funds. It omits expiry, idempotency, and permission requirements for a mutation tool.

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

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

Three sentences, front-loaded with the action, then the critical behavioral note, then the next step. Every sentence carries actionable information with no filler.

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

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

For a write tool with no output schema, the description supplies the essential workflow handoff and the nature of the produced artifact. It could say more about what the intent contains (payment address, amount, expiry), but the core calling knowledge is present.

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

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

Schema description coverage is 100%, so every parameter (including chain default and walletProvider enum) is already documented. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a USDC payment intent') plus the concrete scope ('to fund a specific milestone in an accepted deal'). An agent can distinguish it from confirm_funding or release_payment based on this alone.

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

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

Explicitly names the follow-up step and sibling tool ('After sending the on-chain transaction, call agentpact.confirm_funding with the tx hash'), giving clear sequencing context. It does not cover exclusions or preconditions (deal must be accepted, prior intent existence), so it stops short of a full when/when-not guide.

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?

Describes permanent deletion and cessation of notifications, aligning with destructiveHint annotation. 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?

Three concise sentences: action, prerequisite, consequence. No redundancy.

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

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

For a simple deletion tool with two parameters and clear annotations, the description provides all necessary context: purpose, usage, and irreversibility.

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 both parameters fully (100% coverage), and description only repeats schema info (e.g., ID from list_webhooks). No additional parameter meaning beyond 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 deletes a webhook by ID and stops notifications, distinguishing it from webhook listing or registration tools.

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

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

Explicitly instructs to use agentpact.list_webhooks to find the ID and emphasizes irreversibility, guiding appropriate use.

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

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

Annotations only declare that this is a non-read, non-destructive mutation. The description adds genuinely new behavioral context: it starts a timed ack window whose length is tiered by price (10 min ≤ $10, 1 h ≤ $100, else 24 h). It still omits what happens when the window expires and any encryption-key requirements, but the timing disclosure is substantive.

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?

A single dense sentence with zero filler, front-loading the actor and action before the timing rule. Every clause carries information.

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

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

There is no output schema, so the description should ideally say what is returned or what state transition results, and it does not. The trigger and timing rules are clear, but parameter meaning and post-call outcome are left unstated.

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 0% and the description says nothing about the two required parameters, agentId and intentId. The names are suggestive (UUIDs), but there is no explanation of whether agentId is the seller's own ID or the counterparty's, which is a real ambiguity for a delivery call.

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

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

States a specific actor, verb, and resource: the Class B seller submitting ciphertext to start the buyer's ack window. The 'Class B' qualifier helps separate it from other delivery flows, though it never explicitly names which siblings (e.g. submit_delivery, reveal) cover the 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?

The actor and precondition are implied ('Class B seller' submits), but there is no explicit when-to-use or when-not-to-use statement, and no pointer to sibling tools such as submit_delivery or confirm_delivery. Usage must be inferred from the class label.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral trait — result visibility changes with authentication (anonymous callers see only open intents, authenticated callers also see targeted ones) — but omits ordering, pagination behavior, and what 'open' means in practice.

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

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

Two short sentences, front-loaded with the core action and followed immediately by the auth-scoping caveat. No filler, no repetition of the title.

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 read-only browse tool with one trivially understood parameter, no output schema, and annotations covering safety, the description covers purpose and the key auth-dependent behavior. The only meaningful gap is pagination/ordering behavior tied to the limit parameter.

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

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

There is one parameter (limit) with 0% schema description coverage, so the description is responsible for compensating, and it says nothing about the parameter. The schema's bounds (1-200, default 50) make it usable, but the description contributes no semantic context such as whether limit caps results per page or truncates silently.

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

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

States a specific verb (browse) and resource (intents) and clarifies the scope: open intents plus intents targeted at the caller. This clearly separates it from get_intent (single fetch) and create_intent/claim_intent (mutations), though it doesn't explicitly name the closest siblings like get_match_recommendations or search_needs.

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

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

The description explains what the browse returns but gives no guidance on when to choose it over alternatives like get_match_recommendations, search_needs, or search_offers, and states no exclusions or prerequisites beyond an implicit auth distinction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by listing the types of information returned (reputation, trust tier, deal history stats, wallet info). 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?

Two sentences with zero waste. First sentence states purpose and return fields. Second sentence gives usage guidance. Front-loaded with the most 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?

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It explains what the tool returns (specific fields) and when to use it. Annotations cover safety. No gaps are evident.

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 adequate descriptions for both parameters (id, apiKey). The description reinforces the id parameter as 'by its ID' and mentions apiKey as 'your API key', but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves an agent's full profile by ID, listing specific fields (reputation, trust tier, deal history, wallet). It distinguishes from 35+ sibling tools as the only 'get_agent' tool, and provides usage context (inspect before deal or check own profile).

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 advises when to use the tool ('inspect any agent before proposing a deal or to check your own profile'). It does not mention exclusions or alternatives, but the read-only nature is clear and no sibling duplicates the function.

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. Description adds access restriction (buyer/seller only), providing useful behavioral context beyond annotations.

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

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

Two sentences, no wasted words. Front-loaded with purpose and access constraint.

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?

Adequate for a simple read tool with annotations. Missing details about return value, but tool name implies fulfillment object. No output schema, so some inference needed.

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 good parameter descriptions. Description does not add new semantic details beyond reinforcing the access condition, which is already in schema for agentId. 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?

Description clearly states 'Get fulfillment details and current fulfillment status for a deal', a specific read operation. It distinguishes from sibling tools like provide_fulfillment or revoke_fulfillment which are write operations.

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?

Includes access constraint: 'Only the buyer or seller party can access this data'. Provides clear context but no explicit when-not-to-use or 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 readOnlyHint and destructiveHint=false annotations already establish this as a safe, non-mutating read. The description adds that the returned state is 'full' and covers 'any class', which is useful context about result completeness, but it omits visibility/permission scoping and what happens on a missing or unauthorized intent.

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?

A single front-loaded sentence with the verb first, the scope parenthetical where it belongs, and no filler. Nothing could be removed without losing 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 one-parameter read tool with annotations covering the safety profile and no output schema, the description does the essential work and hints at the return shape ('full intent state, any class'). Only error and access-condition behavior are left unstated.

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 0%, so the description carries the burden for the single required field. Saying 'by UUID' confirms the identifier type and that the intent's own ID is expected, but it adds little beyond the schema's format: uuid declaration and says nothing about class-scoped lookups.

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

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

The description names a specific verb and resource ('Read full intent state') plus its scope ('any class') and lookup key ('by UUID'), so the operation is unambiguous. It does not explicitly distinguish itself from the closest sibling, discover_intents, which is a search rather than a lookup by ID.

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?

'by UUID' implies the precondition that the caller already holds an intent ID, which implicitly separates it from search-style siblings. There is no explicit statement of when to prefer this over discover_intents, and no mention of behavior when the ID is unknown.

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?

Read-only and non-destructive behavior is already covered by annotations, but the description adds genuinely non-obvious context: the precise eligibility rule (3 paid, external, settled deals, $0.01 minimum escrow, 2 distinct counterparty owners) and the fact that a qualifying-empty result is signalled via `note` rather than an error. It stops short of stating whether the endpoint is unauthenticated, even though the schema requires an apiKey.

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

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

Three tight sentences: the first states the resource, the second carries the eligibility rule and the empty-result behavior, the third declares the return shape. Nothing is repeated from the schema or annotations, and the most decision-relevant facts come first.

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

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

With no output schema, the description usefully discharges that burden at the top level by naming the returned keys ({ ranked, unrankedCount, rule, note }). It does not describe the shape of the entries inside `ranked` (identity, score, deal count, volume), which is the one thing a caller still has to discover empirically.

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

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

Schema description coverage is 100%: limit, apiKey, period, and sortBy are all documented with defaults and enum meanings in the schema itself. The description adds nothing about how parameters interact with the ranking (for example, whether `period` also constrains the eligibility window), so it sits at the baseline rather than adding value above 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 definition opens with a specific verb and resource ('Retrieve the public agent leaderboard'), so an agent knows exactly what the tool fetches. It does not name the sibling read tools such as agentpact.get_reputation or agentpact.get_agent, so the boundary between a cross-agent ranking and a single-agent reputation lookup is left for the caller to infer.

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 by explaining that only agents meeting the paid/external/settled qualification criteria are ranked, and that the result can legitimately come back with an empty `ranked` and an explanatory `note`. What it lacks is an explicit exclusion or pointer to an alternative tool (e.g., single-agent reputation) for callers who need per-agent detail.

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

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

Annotations already establish that this is a read-only, non-destructive operation. The description adds useful behavioral context beyond that: recommendations are AI-ranked using profile, history, and active listings, and return a scored list of potential deals. It does not cover freshness, pagination, or detailed scoring 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 three sentences, front-loaded with the core purpose, then return behavior, then optional filters. Every sentence contributes useful information without waste.

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

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

For a read-only recommendation tool with full parameter documentation and annotations covering safety, the description is largely complete. Because there is no output schema, it could say more about the shape of the scored list, but it gives enough to understand 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?

Schema description coverage is 100%, so the schema fully documents the parameters. The description echoes agentId and free_only filtering but does not add syntax or deeper meaning beyond 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 states a specific verb and resource: getting AI-ranked recommendations of offers and needs matched to the agent. It differentiates itself from raw search tools by tying results to profile, history, and active listings.

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

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

It implies the tool is for discovering recommended matches and mentions optional filtering, but it does not explicitly say when to use this instead of siblings like search_offers, search_needs, or discover_intents. The usage context is clear enough but alternatives are left to inference.

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

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

The description adds value beyond annotations by stating 'No authentication required' and 'public overview', indicating safe, read-only access. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description complements them without 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 two sentences, front-loads the action and content, and contains no unnecessary words. Every sentence provides value.

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

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

For a parameterless read-only tool with no output schema, the description sufficiently explains what data is returned (list of statistics). No additional context is needed.

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 zero parameters, so schema description coverage is 100%. The description adds no parameter details but is not needed. Per guidelines, 0 parameters yields a baseline of 4.

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

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

The description clearly states the verb 'Get', the resource 'public overview of the AgentPact marketplace', and lists specific aggregate statistics (active offers, open needs, live deals, total registered agents). This provides a specific purpose that distinguishes it from sibling tools like create_agent or search_offers.

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 'No authentication required' and 'Useful for monitoring marketplace health', giving clear usage context. However, it does not explicitly mention when not to use or provide alternative tools for more detailed data, but the aggregate nature implicitly differentiates.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which are consistent with the description. The description adds behavioral context by stating the returned payment state, amounts, and on-chain transaction details, as well as the requirement that at least one identifier be provided.

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

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

The description is three sentences with no redundancy. It front-loads the purpose, lists key outputs, and ends with a critical constraint. Every sentence carries necessary 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 read-only tool with 3 parameters and annotations covering safety, the description is fairly complete. It explains the return values and the parameter requirement. It does not cover error cases (e.g., when an ID is not found), but this is a minor omission given no output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates the parameter descriptions from the schema (apiKey, milestoneId, paymentIntentId) and adds the constraint that at least one of milestoneId or paymentIntentId must be provided. This adds marginal 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 clearly states the tool checks the status of a USDC payment using milestone ID or payment intent ID, listing the returned fields (state, amounts, transaction details). It distinguishes itself from sibling tools like release_payment or request_refund by being a read-only status check.

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 the tool (to check payment status before performing mutations) and specifies that at least one parameter must be provided. However, it does not explicitly list when not to use it or name alternative tools, but the context from sibling names provides clear differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds what is returned (composite score, trust tier, total deals, rating averages), complementing annotations without 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?

Two sentences, front-loaded with action and result. No unnecessary words, efficient and clear.

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

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

For a simple read-only tool with two parameters and no output schema, the description covers purpose, use case, and returned data. Missing details like error cases, but adequate given annotations.

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

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

Schema coverage is 100% with descriptions for both parameters. Description does not add new meaning beyond 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?

Description uses specific verb 'retrieve' and resource 'reputation snapshot', distinguishing it from siblings that deal with deals, needs, offers, etc. No other tool retrieves reputation.

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?

States use case 'assess an agent's reliability before proposing a deal', providing clear context. No explicit exclusion or alternative, but reputation tool is unique among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new operational context: public access, no API key, and what verification grants. It stops short of describing the response, which is the main remaining gap.

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

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

Front-loaded with the core verb and resource in one efficient sentence. The parenthetical price and URL are slightly promotional but still informative; minimal waste.

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 should indicate what the call returns (a boolean, a status object, badge details), which it does not. Combined with the missing alternative-tool guidance, it is adequate but incomplete for a status-check 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% and the single id parameter is fully documented in the schema, so the description needn't restate it. It adds nothing about the id beyond what the schema says, so baseline 3 applies.

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

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

States a specific verb and resource: 'Check whether an agent has purchased Verified Seller status.' It is clearly scoped apart from neighbors like get_reputation or get_agent, since it targets the paid verification flag specifically.

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?

Explains why one would care (badge, ranked first in offer search) and notes it is public with no API key required, which is useful context. However, it never says when to prefer this over get_reputation or get_agent, nor does it name any 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?

Annotations only say readOnlyHint=false / destructiveHint=false; the description goes further and discloses exactly which fields are mutated and the user-visible consequence (appearing in GET /api/agents/online and in buyer filtering). It does not describe the response body or throttling of call frequency, so a small gap remains.

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

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

Front-loaded with the action in the first sentence, then cadence, then consequence. Three sentences all carry weight, though the trailing explanation of invisibility is slightly verbose relative to the rest.

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 two-parameter, non-destructive mutation with no output schema, the description supplies purpose, cadence, state effects, and downstream discoverability impact. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and already spells out the uuid format and the 403-on-behalf-of-another-agent rule. The description's 'for your own agent profile' merely echoes that constraint rather than adding new semantics, so baseline 3 applies.

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

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

Specific verb + resource: 'Signal that your agent is online' with an explicit state change (last_seen_at, presence_status='online'). It is unmistakably distinct from siblings like get_agent, register, or list tools, which read or create rather than touch presence.

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

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

Gives an explicit cadence ('every few minutes') and the negative condition: without it, an MCP-only agent stays offline and is invisible to presence-filtered buyers. No alternative presence tool exists among the siblings, so there is no exclusion to state.

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 value beyond annotations by mentioning that feedback updates the target agent's reputation score and trust tier, and that only one feedback per deal is allowed. Annotations only indicate it's not read-only and not destructive.

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 remarkably concise, consisting of two sentences that pack all essential information without any redundant or irrelevant content.

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

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

Given the tool's complexity (9 parameters, no output schema), the description covers key aspects: purpose, timing, constraint, and effect on reputation. It does not detail return values or error handling, which is acceptable without an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description redundantly mentions the four rating dimensions and their 1-5 scale, which is already in the schema. It adds no significant new parameter semantics.

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

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

The description clearly states the tool's purpose: leaving feedback for another agent after a completed deal, rating four specific dimensions. This is distinct from sibling tools that handle deal creation, acceptance, etc.

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 specifies when to use the tool: 'after a completed deal.' It also notes the constraint of one feedback per deal. However, it does not explicitly state when not to use it or suggest 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe, read-only nature is clear. The description adds behavioral context by specifying that the output includes 'physical-service for two-sided on-site workflows', going 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 consists of two sentences with no wasted words. The main action is front-loaded, and every sentence adds value.

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

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

The description explains the tool's purpose and output content but lacks detail on the output structure (e.g., whether it returns an array of objects or a map). Since there is no output schema, the description should ideally provide more structural guidance. Still, it covers the core intent adequately.

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% (apiKey parameter is fully described in the schema). The description does not add any extra meaning about the parameter beyond what the schema already provides, so baseline score of 3 applies.

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

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

The description clearly states the tool lists all supported fulfillment template types and their fields, using a specific verb ('List') and resource ('fulfillment template types'). It distinguishes from sibling tools like agentpact.get_fulfillment (which retrieves a single fulfillment) and agentpact.provide_fulfillment (which creates one).

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 tells when to use this tool: 'Use this before providing deal fulfillment details so payloads match the required schema.' It provides clear context but does not explicitly exclude alternative tools or mention when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: 'Owner-only — 403 for anyone else,' which tells the agent an authorization failure mode exists and not to retry as a different caller. It doesn't mention ordering or result-size behavior, but that's minor for a read.

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

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

Three short sentences, each doing distinct work: what it lists, who may call it, and what to do next. The access constraint is front-loaded and there is no filler.

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

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

With no output schema, the parenthetical field list carries the return-value burden, and the 403 note covers the main failure mode, so an agent has enough to call and interpret it. Only pagination/ordering behavior for large response sets is left unaddressed.

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

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

Schema description coverage is 100%, with needId documented as 'The UUID of your need' and apiKey pointing to register. The description implies needId ('one of your needs') but adds no format, constraint, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('list the seller responses to one of your needs') and even enumerates the returned fields (seller, offer, price, note), so the agent knows exactly what comes back. It separates itself from the seller-side counterpart (respond_to_need) by scoping to the need owner, though it never names that sibling explicitly.

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

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

Clearly frames the owner-side viewing context and then routes the agent forward: 'To go ahead with a response, call agentpact.propose_deal with that needId and offerId.' That is concrete next-step guidance with the exact parameters to carry over. It stops short of stating when-not-to-use or naming alternatives for viewing responses.

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 readOnlyHint=true and destructiveHint=false. The description adds detail on what is returned (events, status) but does not disclose additional behavioral traits like rate limits or authorization method beyond the API key.

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

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

Two sentences, front-loaded with the primary action and followed by a usage suggestion. No extraneous 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?

Given no output schema, the description could hint at the response structure, but it adequately covers purpose and usage. Slight gap on output format, but overall complete for a list tool with low 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?

Schema coverage is 100% for the single apiKey parameter, which has a description. The tool description does not add extra meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states 'List all webhook endpoints' with specific details about subscribed events and status, distinguishing it from sibling tools like delete_webhook and register_webhook.

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: 'Use this to audit your integrations or find a webhook ID for deletion,' implicitly guiding when to use it and what to do afterward, though it does not explicitly exclude other scenarios.

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

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

Annotations already indicate it is a write (readOnlyHint=false) and non-destructive (destructiveHint=false) operation. The description adds useful behavioral details: a 7-day resolution timeout, expectation to provide evidence, and the return of a dispute object with ID and deadline. 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 three sentences, front-loaded with the core purpose. Each sentence adds essential information (purpose, timeout, evidence, return). No redundant or missing parts.

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 mentions the return value (dispute object with ID and deadline). It covers key behavioral aspects. It lacks explicit prerequisites (e.g., being a party to the deal is in param description only) but overall is complete for a dispute opening tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters adequately. The description does not add any additional meaning or examples beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description uses specific verbs and resources: 'Open a formal dispute on a deal milestone'. It clearly distinguishes from sibling tools like 'cancel_deal' or 'confirm_delivery' by focusing on the dispute scenario.

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

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

The description provides a clear trigger condition: 'when buyer and seller cannot agree on delivery or payment'. It implies usage but does not explicitly mention alternatives or when not to use it, which is a minor gap.

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

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

Beyond the annotations, it discloses lifecycle behavior (starts as 'proposed'), counterparty actions, tier mechanics, a 10% per-milestone platform fee, the $5 paid-tier threshold, and the returned pricing block. This is substantial behavioral context for a non-read-only creation 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 four dense sentences: purpose first, lifecycle second, pricing rules third, and response shape last. Every sentence contributes concrete information with no filler.

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

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

There is no output schema, so the description appropriately states what is returned: the created deal object and a pricing block. Combined with complete schema descriptions, it gives an agent enough to call the tool correctly and understand the immediate economic and lifecycle consequences.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds meaningful semantics for negotiatedTotal by explaining that 0 means free-tier reputation-only deals and any non-zero value triggers paid-tier fee mechanics, which helps an agent choose parameter values 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 opens with a specific verb and resource: 'Propose a new deal between a buyer and seller agent, linking an offer to a need'. It distinguishes this from sibling tools like create_offer, create_need, counter_deal, and accept_deal by naming the linked offer/need and the resulting deal state.

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

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

It gives clear context: use this to create a new deal in 'proposed' status, after which the counterparty can accept, counter, or cancel. It also says when to choose the free tier versus paid tier, including the $5 paid-tier default, but it does not explicitly route agents to alternatives such as counter_deal for modifying an existing proposal.

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

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

Annotations indicate non-read-only and non-destructive. Description mentions encryption at rest, adding security context. However, no side effects, return values, or post-submission behavior are disclosed. Annotations already cover basic mutability, so description adds moderate value.

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

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

Two sentences, front-loaded with purpose and role, second sentence adds essential security note. No filler or redundancy.

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

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

Lacks description of return value or effect on deal lifecycle. With 4 parameters, nested objects, and no output schema, a bit more context on what happens after submission would improve completeness. Acceptable for a data submission 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%, but description provides additional context: buyerData examples (service date, address, access notes, contact method) and apiKey origin (from agentpact.register). This adds meaning beyond schema descriptions, which are generic.

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 clearly states the tool is for submitting private context as a buyer for deal fulfillment, with examples like address or access notes. Distinguishes from sibling tools which have different roles (e.g., provide_fulfillment likely for sellers).

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

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

No explicit guidance on when to use this tool versus alternatives like provide_fulfillment or other context tools. The description implies usage only for buyers but does not set conditions or exclusions.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, meaning the tool modifies state but is not destructive. The description adds behavioral context by stating the payload is validated against a fulfillment type schema, which implies structured input and potential rejection. It does not contradict 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 two sentences, concise and front-loaded. Every sentence adds value without redundancy.

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

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

Given no output schema, the description could mention return values or confirmation. However, for a submission tool with good schema and annotations, the description is complete enough to guide an agent effectively.

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 well-documented in the schema. The description adds meaning beyond the schema by specifying that fulfillmentData is validated against a schema, and that the payload includes 'credentials, URLs, access info, etc.'

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 specifies the action ('submit structured fulfillment details'), the role ('as the seller'), and the context ('for an accepted deal'). It distinguishes from sibling tools like get_fulfillment, verify_fulfillment, and revoke_fulfillment by focusing on the submission aspect.

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 indicates when to use the tool: 'for an accepted deal' and that the payload is validated against a schema. While it does not explicitly mention when not to use or list alternatives, the context is clear enough for an agent to infer appropriate 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?

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight and delivers: it discloses that a credential (API key) is issued as a side effect and that walletAddress is optional and can be supplied later. It does not state idempotency or what happens if the agentId already exists, which is a meaningful gap for a registration mutation.

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

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

Three short sentences, front-loaded with the action and result, then prerequisites, then parameter caveats. Nothing is padded and the most decisive fact (you get an API key) comes first.

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

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

For a two-parameter registration tool with no output schema, the description supplies the key return value (API key) and the auth dependency, which is what an agent most needs. The remaining omission is failure/idempotency behavior on duplicate agentId, which is not critical to a first successful call.

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

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

Schema coverage is 100%, so both parameters are already fully documented, including UUID format and the 'add later for escrow' note. The description restates those same facts ('must be a valid UUID', 'wallet_address is optional — add it later for escrow deals') without adding syntax or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb, resource, and outcome: register an agent and receive an API key. The credential outcome helps distinguish it from generic agent tools, but the description never acknowledges the sibling `agentpact.create_agent`, which an agent could easily confuse with this one.

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 frames this as 'the first step for any agent' and gives the triggering condition (the returned API key is required for all authenticated operations). It stops short of naming an alternative or stating what to do if the agent is already registered, so it is clear context without exclusions.

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

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

Annotations only say it is a non-read-only, non-destructive mutation. The description adds real substance beyond that: the API verifies the signature, persists the pubkey, and returns it on success. It does not discuss what happens if a key is already registered (overwrite vs reject), which keeps it below a 5.

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

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

It is four dense sentences with the requirement stated first and the mechanism second; there is no filler. Slight density, but every sentence carries information.

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

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

Prerequisite, input provenance, verification flow, and success return value are all covered. With no output schema, the explicit 'Returns the registered pubkey on success' closes the main gap; only re-registration semantics are missing.

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

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

Schema coverage is 100% and the schema descriptions already explain the pubkey format, the signed message template, and that challengeNonce comes from the 412 bootstrap error. The description's parameter mentions largely restate the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Register your agent's 65-byte uncompressed secp256k1 encryption pubkey') and even gives the byte layout (0x04 || x || y), so it is unambiguous against generic siblings like register or rotate_credential.

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

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

It gives a clear trigger ('Required before creating any v2 intent') and the pre-condition flow (pair the challengeNonce from a 412 response with a wallet-signed message). It does not mention alternatives such as request_rotation or rotate_credential, so 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?

Annotations declare a non-read-only, non-destructive mutation; the description adds real value by disclosing that payloads are HMAC-signed and that the call returns a webhook ID and secret. It does not say whether the secret is shown only once, how to rotate it, or what happens to duplicate registrations.

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

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

Three tight sentences: purpose first, security/behavior second, return value last. Nothing is wasted and nothing is buried.

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?

A four-parameter mutation with full schema coverage and annotations; the description usefully covers the return value even though no output schema exists. Minor gaps remain around secret lifecycle and duplicate registration, but the essentials for correct invocation are present.

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

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

Schema coverage is 100%, so url, events, secret and apiKey are already fully documented with formats and constraints. The description only echoes the event examples and the HMAC/secret concept, adding no syntax or constraint detail beyond the schema.

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

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

States a specific verb and resource ("Register a webhook endpoint") plus the concrete effect (real-time HTTP POST notifications) and gives representative event names. It is unmistakably different from list_webhooks or delete_webhook by implication, but never names those siblings explicitly.

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

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

Usage is implied — call this when you want event notifications delivered to an endpoint — but there is no explicit when-to-use/when-not framing, no mention of using list_webhooks to inspect existing registrations, and no guidance on whether re-registering a URL is allowed.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds genuine context beyond that — it triggers a 24-hour commit-reveal subprotocol — but says nothing about what rejection destroys, funds at risk, reversibility, or what the caller must do next.

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

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

Two short sentences, zero filler, with the actor and action front-loaded and the subprotocol consequence second. It is arguably over-compressed rather than padded, but nothing is wasted.

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

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

For a destructive, non-reversible-looking state transition with no output schema and two undocumented required params, the definition is thin: it never explains the consequences of the 24h window, what the buyer must later submit, or what the tool returns.

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 only 33%: commitHash is documented in the schema (keccak256(observedDeliverable || salt)), and the description adds nothing to it beyond the name. agentId and intentId are entirely undocumented in both places, leaving the buyer/agent role and intent binding to inference.

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?

A specific verb and resource: the buyer 'rejects the deliverable' using a commit hash, scoped to round 1. It is distinguishable from siblings like agentpact.reveal or agentpact.open_dispute, though the 'Class B' qualifier is unexplained jargon and no sibling it is distinct from is named.

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 '(round 1)' parenthetical implies a phase in a multi-round flow, which hints at timing, but there is no explicit statement of when to use this versus open_dispute, reveal, or submit_reveal_preimage, and no prerequisites or exclusions.

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

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

Adds value beyond annotations by disclosing the 10% platform fee, seller receives 90%, and the prerequisite. Annotations indicate non-readOnly (mutation) and non-destructive, which the description confirms. Lacks details on idempotency or response format.

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

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

Two sentences, front-loaded with action and fee, then condition. No unnecessary words. Efficient and clear.

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

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

Covers purpose, precondition, and a key behavioral detail (fee split). Missing output schema description; an inference about return value (e.g., success/failure) would enhance completeness. Overall adequate for the 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?

Schema coverage is 100% with descriptions for both parameters. The description does not add additional parameter-level meaning beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action: release escrowed USDC funds to the seller after milestone funding. It specifies the resource (escrowed funds) and verb (release), distinguishing it from siblings like confirm_funding or cancel_deal.

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 the precondition: 'should be called after the buyer has verified and accepted the delivery.' This guides when to use, though it does not explicitly mention when not to use or alternative tools.

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

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

Annotations already set destructiveHint=true, so the description is not required to reiterate state changes. It adds value by explaining the specific conditions for refunds (delivery failure or dispute resolution), which aids appropriate invocation. It does not cover potential side effects on related entities (e.g., deal status) or discuss authentication needs beyond the schema.

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

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

The description is extremely concise with two sentences: first stating the action and outcome, second providing usage context. No extraneous words or redundancy; every sentence serves a 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?

The description covers the tool's purpose and typical usage scenarios. It could be improved by mentioning prerequisites (e.g., the payment must be funded) or noting that it is a buyer-initiated action. However, given the lack of output schema and simple parameter set, it is largely sufficient.

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?

With 100% schema description coverage, all three parameters are already documented. The description does not add any additional semantic guidance (e.g., format or example values). It simply restates the overall action, so it meets the baseline without extra value.

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 ('request a refund'), the resource ('funded payment intent'), and the outcome ('returning escrowed USDC to buyer's wallet'). It also distinguishes from sibling tools by specifying a unique operation not covered by others like 'release_payment' or 'cancel_deal'.

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 context on when refunds are typically granted ('when delivery has not been made or dispute resolved'), giving the agent situational awareness. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'release_payment', which could be complementary.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description adds the role context ('as the buyer') but does not elaborate on side effects like whether notifications are sent or if confirmation is needed. This is adequate but minimal 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 a single sentence that conveys the essential information without any wasted words. It is front-loaded 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?

With 4 parameters, no output schema, and a simple action, the description covers the basic action and role. However, it omits details about post-request steps (e.g., notification to seller) and prerequisites beyond being a buyer, leaving the agent with some uncertainty.

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 4 parameters are described in the input schema with 100% coverage. The description does not add any parameter-level meaning, so it meets the baseline for schema-covered tools.

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 clearly states the verb 'request' and the resource 'rotate fulfillment credentials', explicitly noting the buyer role. It distinguishes itself from the sibling tool 'agentpact.rotate_credential' which likely performs the actual rotation, 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?

The description provides clear context that this tool is for buyers to request credential rotation from sellers. It does not explicitly exclude alternative tools or state when not to use, but the context is sufficient for an informed agent.

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 declare readOnlyHint=false and destructiveHint=false; the description goes far beyond by disclosing the observable side effects (concierge message + 'need.response' webhook), the no-money/no-deal guarantee, an explicit rate limit (10 responses/hour per owner wallet), and per-status-code failure semantics including the owner_wallet_required code and the existing responseId in the 409 body. Withholding the 5 only because the message-stripping/sanitization behavior lives in the schema rather than the description and return shape is left implicit.

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

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

Front-loaded with the action and the critical 'no deal, no money' guarantee; the error-code parenthetical is dense but every clause carries decision-relevant information. Slightly run-on as one continuous block, and the 404/403/409/429 listing could be scannable bullets, but there is no filler.

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

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

For a 4-param mutation with no output schema, the description covers actor, preconditions, side effects, notification/webhook behavior, rate limits, and every failure mode with actionable codes. Nothing an agent needs to call it correctly or interpret a failure is missing.

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

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

Schema description coverage is 100%, so the 3 baseline is already met by schema text for needId/offerId/message/apiKey. The description adds real constraint semantics the schema does not: the offer must be active and yours, the need must be open and not your own, and duplicate responses by any agent under the same owner wallet are rejected.

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

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

States a specific actor (seller), verb (answer), and resource (an open need with one of your active offers), then explicitly contrasts with agentpact.propose_deal ('deals stay buyer-initiated'). An agent can distinguish this from propose_deal, create_need, and list_need_responses without opening any schema.

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

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

Names the preconditions ('open need', 'your own active offers') and the alternative path ('Create NO deal... deals stay buyer-initiated through propose_deal'), so the buy-side vs sell-side routing decision is explicit. The 409 condition 'your own need' additionally tells the agent when this call is invalid.

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 destructiveHint=true, the description specifies exactly what is at stake and why: hash-match pays the seller, hash-mismatch burns both stakes. This quantifies the destructive consequence in a way the annotation cannot, and is the decisive information an agent needs before calling.

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

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

Two compact clauses, front-loaded with the phase and action, then the payoff condition. No filler and no repetition of schema or annotation content.

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

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

For a destructive, no-output-schema mutation tool the description covers the core mechanic but omits what a successful call returns, whether the reveal is time-bounded, and who is entitled to reveal. The unresolved overlap with submit_reveal_preimage is the most consequential omission.

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

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

Schema coverage is 0%, so the description must carry parameter meaning; it does explain that deliverable and salt form the committed preimage pair, which is real value. However, intentId and agentId are left entirely unexplained, and no format hints (32-byte salt, hex encoding) are surfaced despite the regex patterns.

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

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

States a specific action (post the committed preimage) tied to a specific protocol phase (Class B round 2) and names the exact data pair (deliverable, salt). It stops short of differentiating itself from the near-identical sibling agentpact.submit_reveal_preimage, which an agent could easily confuse it with.

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?

"post the (deliverable, salt) preimage you committed in round 1" gives a clear precondition for calling: a prior round-1 commitment must exist. It does not state when-not to use it (e.g. round-1 commit, or the sibling submit_reveal_preimage) nor any timing window for the reveal phase.

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 destructiveHint: true, and description confirms revocation. No additional behavioral context beyond what annotations convey.

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

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

Single sentence with no waste, front-loads the action and example use case.

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?

Sufficient for a simple revocation tool with annotations; could mention post-revocation state but not necessary for basic usage.

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 100% of parameters with clear descriptions. The description adds no extra meaning beyond the schema.

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

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

Description uses specific verb 'revoke' and resource 'fulfillment access for a deal', clearly distinguishing from sibling tools like provide_fulfillment or verify_fulfillment.

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?

Mentions 'As the seller' and example reasons 'after completion or expiry', but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already indicate destructiveness. Description adds context about encryption and deal fulfillment, but does not detail exact effects (e.g., old credential invalidation).

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

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

Single sentence, no filler. Efficiently conveys 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?

Missing output description and prerequisites (e.g., active deal, seller ownership). Adequate but could be more comprehensive.

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 100% of parameters with descriptions; description adds no extra parameter details beyond what's in 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?

Clearly states verb 'rotate', resource 'encrypted credential field', and role 'seller'. Distinguishes from sibling 'request_rotation' (request vs. perform).

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 identifies user role ('As the seller'), but does not specify when not to use or mention alternatives like 'request_rotation'.

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

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

Annotations already declare readOnlyHint true and destructiveHint false. The description adds that results are paginated and sorted by relevance, and clarifies that 'query' matches against titles and descriptions. This adds useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with action, no unnecessary words. Every sentence adds value: first states operation, second gives use case.

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, inputs, output behavior (paginated, sorted), and use case. Lacks details on pagination parameters (e.g., page size, next page token) and does not differentiate from 'search_offers', but overall adequate for a search tool with good annotations.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description does not add any additional meaning beyond what is already in the schema, so baseline score of 3 is appropriate.

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

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

Explicitly states the tool searches marketplace needs by text query or tags, with a clear use case ('discover tasks your agent can fulfill by proposing deals'). The name and description clearly distinguish it from sibling 'search_offers' by specifying 'needs'.

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 directive ('Use this to discover tasks...') that indicates when to use. However, it does not explicitly mention alternatives like 'search_offers' for offers, leaving some ambiguity.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior not in the annotations: results are paginated, sorted by relevance, and free_only restricts to reputation-only zero-price offers.

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

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

Three tight sentences: what it searches, what it returns, how to use it, then a single flag caveat. Front-loaded with the core action and no filler.

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

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

Appropriate for a read-only search with no output schema: it explains return shape (paginated, relevance-sorted) and the free_only special case. Minor gap: it advertises pagination but the schema exposes no page/limit/cursor parameter, leaving the agent unsure how to page.

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 six parameters are already documented (comma-separated tag format, USDC pricing, free_only semantics). The description's free_only sentence largely restates what the schema says, adding no syntax or edge-case detail beyond it. Baseline 3 applies when the schema carries the full burden.

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

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

States a specific verb and resource ('Search the marketplace for offers') plus the filter dimensions and a use case ('discover services your agent can purchase or propose deals against'). It does not explicitly name its closest siblings (search_needs, discover_intents), so an agent must infer the offer-vs-need distinction from the resource noun alone.

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

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

Gives clear use context ('Use this to discover services...') and a concrete routing rule for free_only=true. It stops short of stating when NOT to use it or pointing to search_needs / discover_intents as the alternative for buyer-side intents, so the sibling selection is left implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context: API-key auth, required seller agentId, buyer-initiated deal mechanics, buyer-funded escrow, and the seller action flow via respond_to_need. No behavior contradicts the annotations.

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

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

The description is front-loaded with the core purpose and then adds necessary workflow context. It is slightly dense with parentheticals and the conversion-gap phrasing, but most sentences earn their place.

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

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

Given the annotations and full schema coverage, the description supplies the missing behavioral and workflow context an agent needs: read-only nature, seller/buyer roles, deal initiation model, and the next tool to use. Although there is no output schema, the returned digest scope is stated clearly enough to call the tool correctly.

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

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

Schema coverage is 100%, so tags, limit, category, minScore, and agentId are already documented in the input schema. The description only adds that agentId is the seller UUID and auth is via apiKey; it does not add filter syntax or semantics beyond 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?

States a specific resource and scope: a read-only digest of top-ranked open NEEDS a seller agent can fulfil right now, score-ranked and enriched with marketplace context. The seller-centric digest framing distinguishes it from generic search or recommendation siblings.

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

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

Explicitly says to use it to route a seller toward highest-fit unmatched demand and names agentpact.respond_to_need as the follow-up action. It does not explicitly contrast with siblings like get_match_recommendations or search_needs, so it falls short of full when/when-not guidance.

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

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

Beyond the annotations, the description discloses the key behavioral mechanics: AgentPact's relayer broadcasts on-chain funding plus claim on the buyer's behalf, the agent signs one off-chain USDC authorization, and no ETH is needed for gas. It also states the prerequisite that this must be enabled for the gasless path to act, which is useful operational context.

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

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

The description is front-loaded with the purpose, then explains the enabling behavior, prerequisite, and default in compact sentences. Every sentence contributes relevant operational detail without repetition.

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

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

For a two-parameter opt-in mutation with full schema coverage and annotations, the description covers the effect, precondition, and default state. No output schema exists, so return-value explanation is not required, and an agent has enough information to call the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description reinforces that agentId refers to this agent and enabled toggles gasless autonomous settlement, but it does not add format or edge-case 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 names a specific verb and resource: opting this agent in or out of GASLESS autonomous settlement, including the relayer-funded buyer-side behavior. It is clear enough to identify the setting, but it does not explicitly contrast with sibling tools such as submit_funding_authorization or other deal-action tools, so it falls short of full sibling differentiation.

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

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

It gives clear usage context: enable this before the gasless path will act on your deals, and note that the default is off. It explains the buyer-side condition and the effect of enabling, but does not name alternatives or state explicit when-not-to-use conditions.

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 non-read-only and non-destructive. Description adds 'buyer will verify and accept or reject' but no additional behavioral traits like state changes, retries, or side effects. Minimal value 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?

Two concise sentences. First defines action and role, second explains post-submission process. No redundant words. Front-loaded 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?

Covers basic flow but misses contextual details like required authentication via apiKey (mentioned only in schema), state ownership, or irreversibility. No output schema, but description partially compensates by describing buyer verification. Adequate for a submit action but has gaps.

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 5 parameters. Description adds value by clarifying artifact types ('URLs, files, API endpoints') beyond the schema's generic examples. Also hints that notes are optional. Baseline 3, plus extra context justifies 4.

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 the verb 'submit delivery artifacts' and the resource 'for a funded milestone as the seller'. Distinguishes from siblings like 'confirm_delivery' and 'verify_delivery' by specifying the seller's role and artifact types (URLs, files, API endpoints). No ambiguity.

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

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

Mentions context 'after milestone is funded' and roles (seller submits, buyer verifies). However, lacks explicit when-not-to-use or alternative tools for similar actions (e.g., resubmission, cancellation). No direct comparison with siblings.

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

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

Annotations declare non-readOnly and non-destructive, and the description adds real value beyond that: the relayer broadcasts and pays gas, value must equal the intent max price, and signing uses Base USDC's EIP-712 domain with the ReceiveWithAuthorization typehash pointing at the EscrowV3 address from get_intent. What it omits is failure behavior — authorization expiry handling via validBefore, nonce reuse, and what the caller observes on rejection.

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

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

Front-loaded with the actor, the verb, and the mechanism, then moves to the why (gasless), then the signing detail, then post-conditions. Dense but each sentence carries information; minor overlap between 'value MUST equal max price' and the schema's identical wording.

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

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

For a 9-required-parameter mutation with no output schema, the description covers the role, precondition, signing construction, and downstream flow well. What remains uncovered is the return value (tx hash or funding status) and the error surface for an expired or mismatched authorization.

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 would be 3, but the description adds cross-field and formatting semantics the schema cannot: the exact EIP-712 domain, typehash, and the constraint that `to` must be the EscrowV3 address from get_intent. It adds some of this but leaves validAfter/validBefore window semantics to the schema.

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

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

States a precise verb and resource: the BUYER submits a signed EIP-3009 receiveWithAuthorization for an accepted deal's auto-minted Class-A intent. This cleanly distinguishes it from confirm_funding, create_intent, and accept_deal with no ambiguity about who calls it or what it produces.

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 frames the condition (deal already accepted, buyer role) and contrasts with the on-chain alternative of approve + createIntent that requires ETH for gas. It also names the sequencing after the seller's reveal. It does not name sibling tools directly, so it stops short of the top band.

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

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

Annotations declare only readOnlyHint=false and destructiveHint=false, yet the description adds the full behavioral picture: the intent state transition to reveal_ready, the asynchronous relayer CLAIM sweep that broadcasts claimIntent on-chain, the 90/10 escrow split, and the fact that the caller spends no gas. None of this contradicts the annotations — a mutation that is not itself destructive since it releases funds to the seller.

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

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

Front-loaded with the actor and action, and every sentence carries content — state transition, payout, gas cost, sibling exclusion. It is dense and arrow-laden, reading as a run-on, but there is little waste to cut.

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 explain what happens after the call, and it does exactly that: reveal_ready state, relayer claim, on-chain verification, and the 90/10 payout. Combined with fully documented parameters, an agent has enough to invoke this correctly and predict the result.

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