agent-escrow

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

Annotations already declare readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds useful context beyond that: it is 'free' (no cost/side effects) and it returns the full action-and-input inventory, which tells the agent what to expect from 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?

Two short sentences, front-loaded with the returned payload and followed by the usage directive. Minor redundancy in restating 'describe this agent' from the name, but nothing wasteful enough to penalize further.

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

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

For a zero-parameter discovery tool with an output schema present, the description supplies everything needed: what it returns, that it is read-only and free, and that it should be invoked first. Given the rich annotation set and output schema, no gaps remain.

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

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

The tool takes zero parameters, so per the baseline rule this scores 4. The description correctly implies there is nothing to supply by framing the call as an unconditional discovery step.

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 (describe) and resource (this agent) and enumerates the exact content returned: name, version, purpose, supported actions, and each action's inputs. This is unmistakably a self-discovery/meta tool, which no sibling (create_meter, record_usage, sla_report, etc.) duplicates.

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 call-ordering rule: 'call it first to learn how to use this server.' That is strong, actionable when-to-use guidance. It does not explicitly say when not to call it (e.g., after the server capabilities are already known), which is why it falls short of a 5.

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

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

Annotations only declare it is a non-read-only, non-idempotent, non-destructive write; the description adds the genuinely useful behavioral fact that funds become locked pending arbitration by agent-arbitration-agent. It does not cover what happens if the escrow is not FUNDED, who may file, or whether a dispute can be withdrawn.

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 state transition, no filler. Every clause carries information an agent needs.

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

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

An output schema exists so return values need not be described, and the escalation flow is explained. However, for a non-idempotent state-changing tool with 0% schema coverage on two parameters, missing failure modes and the unexplained 'reason' parameter leave it only minimally complete.

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

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

Schema description coverage is 0%, and the description mentions neither parameter. The optional 'reason' field in particular is left completely unexplained — its default, purpose, and whether it is surfaced to the arbiter are all undocumented, so the description fails to compensate for the schema gap.

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 ('Move') plus the exact state transition FUNDED -> DISPUTED on the escrow resource. This immediately distinguishes it from siblings like release_escrow and refund_escrow, which terminate an escrow rather than escalate it.

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

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

The precondition 'a FUNDED escrow' tells the agent when this tool is applicable, and the second sentence explains what happens next (arbiter resolves). It stops short of explicitly naming release_escrow/refund_escrow as the paths to use instead when no dispute is needed.

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

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

Annotations already establish read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The word "current" mildly implies retrieval of the latest state rather than history, but the description adds no further behavioral context such as freshness, permissions, or error 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 a single short sentence with no wasted wording and is front-loaded. Its terseness is more a completeness problem than a conciseness problem.

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 one-parameter read tool with an output schema and rich annotations, the definition is minimally adequate. However, it leaves ambiguity about the returned record's scope and its relationship to list_escrows.

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 should compensate for the undocumented escrow_id parameter, but it says nothing about the parameter's meaning, format, or source. The parameter name is self-evident but the description adds no semantic 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 "Current record for an escrow" essentially restates the tool name and title without a clear verb or distinguishing scope. It does not clarify how this differs from siblings such as list_escrows or the escrow mutation 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?

There is no explicit guidance on when to call escrow_status versus list_escrows or other escrow-related siblings. The intended use must be inferred entirely from the tool name.

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

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

The description asserts '(idempotent)' while the supplied annotations declare idempotentHint=false. These directly conflict on the single behavioral property that matters most for safe retry logic, so the description actively misleads rather than adding context.

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

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

Two short sentences with the state transition front-loaded and the secondary parameter note following. No padding 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?

An output schema and annotations exist, so return values and safety profile need not be spelled out. However, the description omits what happens on an invalid state, whether partial funding is possible, and contradicts the idempotency annotation — gaps that matter for a money-moving state transition.

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 must carry the meaning. It does explain payment_ref as linking the payment-rail transaction, which is genuinely useful, but escrow_id is left completely undefined and no format or constraint is given for either parameter.

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

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

The description names a specific state transition — marking an escrow from OPEN to FUNDED — which is distinct from every sibling (open_escrow, release_escrow, refund_escrow, dispute_escrow). The verb, resource, and precondition are all present in one compact phrase.

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 precondition 'an OPEN escrow' tells the agent exactly when this tool applies, which is meaningful routing guidance within an escrow lifecycle. It stops short of explicitly naming alternatives or saying what to do when the escrow is not OPEN, so it does not reach 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that filtering is optional but does not disclose pagination, ordering, or what a null state returns—minor gaps given the annotations and output schema.

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

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

The description is a single, front-loaded sentence with no wasted words. The core action and the optional filter are communicated efficiently.

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

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

For a simple list tool with one optional parameter, an output schema, and rich annotations, the description is nearly complete. It covers the action and filter values, with only minor omissions like ordering or default behavior when state is null.

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

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

The schema has zero description coverage for the single 'state' parameter, so the description must compensate. It does so well by listing the valid enum values (OPEN|FUNDED|RELEASED|REFUNDED|DISPUTED) and clarifying that the filter is optional, though it does not explicitly state that omitting state returns all escrows.

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 ('List') and resource ('escrows'), making the tool's core function clear. It does not explicitly distinguish itself from siblings like escrow_status, but the purpose is unambiguous.

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

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

The only usage hint is 'optionally filtered by state,' which describes the parameter, not when to use this tool instead of alternatives. There is no guidance on when to choose list_escrows over escrow_status or other siblings, and no exclusions or prerequisites are mentioned.

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 substantive behavior: the platform fee is computed and frozen at open using ceiling on bps, the escrow is returned in state OPEN, and a replay with open_ref yields the original escrow with duplicate=true rather than a new one (E10). The conditional idempotency described is consistent with idempotentHint=false, which correctly reflects that idempotency only holds when open_ref is supplied.

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

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

The definition is dense and front-loaded, leading with what is created and then the money-unit caveat and idempotency contract. Every sentence carries information, though terms like "ceil bps" and the bare code "E10" are left unexpanded for the reader.

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-moving mutation with an output schema present, this covers what an agent most needs before calling: unit conventions, fee freezing, returned state, and the exact retry contract. The remaining gap, per-parameter meaning for payer/payee/terms/currency/deadline, overlaps with the schema and is minor relative to what is disclosed.

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 burden and it only partly does: amount_minor is defined precisely (positive integer, minor units/cents), open_ref's purpose is explained, and fee_bps behavior is implied by the fee-freezing sentence. payer, payee, terms, currency, and deadline receive no semantic treatment at all, leaving five of eight parameters undocumented.

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 ("Open an escrow between payer and payee") and states the resulting state (OPEN) and return value (escrow_id). It is clearly distinct from siblings like fund_escrow or release_escrow by naming the opening act, but it never explicitly says how it relates to those siblings in the lifecycle.

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 concrete conditional guidance: pass open_ref=<your job id> so a replayed call returns the original escrow rather than minting a duplicate. That is real when-to-use guidance, but there is no explicit statement of prerequisites (e.g., that funding must follow) or 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?

The description does add real behavior beyond annotations: funds go to the payer, and refunding an OPEN escrow acts as a cancel rather than a transfer. But "(exactly-once)" asserts a retry-safe guarantee that conflicts with the supplied idempotentHint=false, creating a conflicting signal about whether a retried call double-refunds. Permissions, failure modes, and what happens to a DISPUTED escrow are also unstated.

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 state constraint and the payer direction front-loaded before the OPEN-as-cancel nuance. Every clause carries information an agent would otherwise have to guess.

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

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

An output schema exists, so return values need not be explained, and the destructive nature is covered by annotations. Still missing for a destructive, non-idempotent money-movement tool: authorization requirements, the DISPUTED-path behavior, and any parameter documentation at 0% schema coverage.

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 parameters, and the description says nothing about escrow_id or reason, so neither field's format or expected values is clarified anywhere. The eligible-state list marginally informs which escrow_id values are valid, but that is far short of compensating for the coverage gap.

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?

"Refund ... escrow to the payer" names a specific verb, resource, and money direction, and enumerates the eligible states (OPEN/FUNDED/DISPUTED), which is more than the title conveys. It does not explicitly differentiate itself from siblings like release_escrow or dispute_escrow, so an agent must infer that release pays the payee rather than the payer.

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 state list (OPEN/FUNDED/DISPUTED) implicitly defines when the tool is applicable and implicitly excludes other states such as RELEASED or already-REFUNDED. However, no alternative tool is named and no explicit when-not guidance is given, so routing versus release_escrow or dispute_escrow is left to inference.

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

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

Annotations declare idempotentHint=false, yet the description states the call is 'exactly-once — a repeat release returns the existing terminal record, never a double payout', which is precisely idempotent behavior. An agent deciding whether a retry is safe would get two opposite answers from the structured field and the prose. The destructiveHint=true and openWorldHint=false claims are consistent, but the idempotency conflict is material.

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 state precondition first and the safety guarantee in parentheses. 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?

An output schema exists, so return-value explanation is not required, and the destructive/monetary nature is stated. However, with two undocumented parameters and an idempotency signal that conflicts with annotations, an agent lacks enough to know how to supply delivery_proof or how to retry safely.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and it largely does not: it never explains that delivery_proof exists, what format it takes, or that it is presumably required when releasing a DISPUTED escrow. Only escrow_id is indirectly implied by the FUNDED/DISPUTED framing.

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 (release) and resource (escrow), plus the exact source states (FUNDED/DISPUTED) and the outcome (payee receives funds). That is enough for an agent to distinguish it from refund_escrow and dispute_escrow 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?

The FUNDED/DISPUTED precondition implies when the tool applies, but it never names the alternatives (refund_escrow, dispute_escrow) or the condition that selects them. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the useful detail that the check is of a tamper-evident hash chain, but says nothing about cost, scope of the chain, or what a failed verification implies.

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 verb and the thing being validated come first, and nothing is redundant.

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

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

For a simple read-only single-parameter check with an output schema and full annotations, this is nearly sufficient. The only real gap is the absence of any hint about what verification covers or when to run it relative to the escrow lifecycle tools.

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

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

Only one parameter and schema description coverage is 0%, so the description must carry the load. It implies the argument is an escrow ('for an escrow'), mapping loosely to escrow_id, but adds no format, identifier source, or validity constraints beyond the schema's type.

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

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

Specific verb ('Validate') plus a specific resource ('tamper-evident audit hash chain') scoped to an escrow. It is clearly distinct from every sibling, which deal with escrow lifecycle mutations or listing/status, though it never explicitly contrasts itself with them.

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

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

Usage is implied rather than stated: the agent can infer this is the integrity-check step alongside escrow_status and list_escrows, but the description gives no explicit trigger conditions (e.g., after release/refund, or when an audit result needs confirmation) and no exclusions.

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