agent-surety

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

The description asserts '(idempotent)' while the annotations declare idempotentHint=false. That is a direct conflict on the single most operationally important property of a mutation tool, and an agent cannot tell whether retrying a call is safe. No other behavioral context (permissions, failure on wrong state, side effects) 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?

Two short sentences, front-loaded with the action and state transition, followed by the one non-obvious parameter's meaning. Nothing is padded or 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?

An output schema exists, so return values need not be described, and annotations cover the read/write and destructive profile. However, for a state-mutating tool the description leaves the retry semantics contradictory and never states the behavior when the bond is not POSTED, which is essential 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?

Schema description coverage is 0%, so the description must carry the parameter burden. It does explain funding_ref meaningfully — the payment rail transaction that funded the stake — but says nothing about bond_id beyond its obvious name, and does not state whether funding_ref is optional or what an empty default implies.

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 on a specific resource — 'Mark a POSTED bond ACTIVE' — including the precondition state, which separates it from post_bond, release_bond, and slash_bond. It stops short of naming any sibling explicitly, so the differentiation is inferred from the state machine rather than stated.

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 'POSTED' precondition implies when the tool applies, but there is no explicit when-not guidance, no statement about what happens if the bond is in another state, and no routing to alternatives such as release_bond or bond_status. Usage is implied rather than prescribed.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds the payload facets (state, balances, claims, audit head), a small but genuine behavioral signal about what the read returns; however, it says nothing about behavior when the bond_id is unknown or about freshness/snapshot semantics.

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

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

One front-loaded sentence with zero filler and no redundancy. It is arguably too terse rather than too long—the efficiency is good but achieved by omitting needed detail.

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

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

An output schema exists, so return-value documentation is not required, and the safety profile is fully covered by annotations. Still, a read tool keyed on an opaque identifier should at minimum say what an ID looks like and what happens on an unknown bond, which this definition omits.

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 bears the burden of explaining the single bond_id parameter, yet it says nothing about format (UUID, hex, integer) or where to obtain a valid ID. The parameter name is suggestive but undocumented in both schema and description.

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 identifies a specific resource (a bond) and enumerates the returned facets (state, balances, claims, audit head), which distinguishes it from siblings like list_bonds and verify_audit. It lacks an explicit retrieval verb, but 'Current record for a bond' is unambiguous enough for an agent to select 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?

There is no when-to-use guidance, no mention of alternatives (e.g., use list_bonds to enumerate, price_bond for valuation), and no prerequisites or error conditions. The agent must infer selection purely from the noun phrase.

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 behavior, so the safety profile is covered. The description adds that the response covers capabilities and the input contract, but does not discuss auth, limits, or return shape, though an output schema exists.

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 one front-loaded sentence with no filler. For a zero-argument introspection tool, this is appropriately minimal.

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?

Low complexity, zero parameters, rich annotations, and an output schema mean little description is needed. It states the return content, though it could do more to signal when an agent should call it instead of the operational sibling 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?

The tool has zero parameters, so there are no parameter semantics to document. The baseline score of 4 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 ('Return') and resources ('capabilities and input contract'), making the introspection role clear. It does not explicitly contrast with the sibling green-certificate tools, so it stops 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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternative; the introspection purpose is only implied by the description and tool name. An agent must infer that this is the discovery or service-description call.

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 a non-read-only, non-idempotent, non-destructive, closed-world write, so the baseline is lower. The description still adds two non-obvious traits beyond them: the ACTIVE-bond precondition and the fact that a claim only pays out if arbitration upholds it. It omits what filing does immediately (fund locking, whether duplicate claims are allowed).

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 action and its precondition, with no filler. The trailing pointer to slash_bond earns its place by routing the agent.

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. However, for a state-changing tool with 0% parameter documentation, the description leaves too much unsaid about the immediate effects of filing and the meaning of its inputs.

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 none of the four parameters (bond_id, claimant, amount_minor, reason) are explained. The only added meaning is that bond_id must point at an ACTIVE bond; the units/scale of amount_minor and the role of reason are left entirely 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?

States a specific verb+resource ("File a claim against an ACTIVE bond") and constrains the target to bonds in ACTIVE state. It references the sibling slash_bond for the payout path, but does not fully separate filing from slashing in an agent's decision, so it stops short of a 5.

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

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

Usage is only implied: the bond must be ACTIVE, and the payout outcome depends on an arbitration ruling reachable via slash_bond. There is no explicit statement of when to file versus use slash_bond or bond_status, and no prerequisites (claimant stake, permissions) are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered without the description. The description adds the enumerated state values, which is real behavioral context, but says nothing about ordering, pagination, or how many bonds come back.

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 sentence with the verb, resource, optionality and permitted values, in that order. Nothing is padded or repeated from 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. With one optional parameter, the only real requirement was documenting the state values, which it does; minor gaps are result ordering and pagination.

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 schema types 'state' as an unconstrained string with no enum, so the description carries the full burden. It discharges that by naming the four legal values (POSTED, ACTIVE, RELEASED, EXHAUSTED) and marking the parameter as optional, adding meaning the schema lacks. It stops short of saying whether matching is exact/case-sensitive.

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 ('List') and resource ('bonds') with its optional filter, so the agent knows exactly what the call returns conceptually. It does not explicitly distinguish itself from nearby siblings like bond_status, but the read/list shape 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 word 'optionally' tells the agent the filter is not required, which is useful usage context. However, it never says when to prefer this over bond_status or why one would pass a state filter, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior — the fee is computed and frozen at post time (2% default) — which tells the agent the cost is locked at creation. However, it never says whether the bond is active immediately or requires activate_bond, whether the principal is charged/escrowed, or what happens on a duplicate post.

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, with the core action front-loaded and the fee-freezing caveat placed where an agent will read it before calling. The only soft spot is the slightly ornamental phrase 'behind an agent's promises,' which costs a few words without adding operational meaning.

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

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

An output schema exists, so return values need not be described, and the fee-freezing detail is a useful addition for a financially consequential mutation. Still, for a 5-parameter write tool with 0% schema coverage, the definition leaves too much unsaid: the role of principal_agent, currency handling, what coverage means, and the post-to-activate lifecycle.

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 burden, and it does explain the two most error-prone parameters: principal as a positive integer in minor units, and expires_at as an ISO-8601 window end. But three of five parameters — principal_agent, currency, and coverage — receive no explanation at all, leaving the agent to guess formats and defaults beyond what the bare schema titles show.

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 surety bond') plus a scope qualifier ('behind an agent's promises'), which distinguishes it from siblings like price_bond, release_bond, and slash_bond. It stops short of explicitly naming which sibling it supersedes or follows, but the creation semantics are 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?

There is no when-to-use guidance and no mention of alternatives, even though the sibling list contains an obvious decision point (price_bond to quote vs. post_bond to commit) and a sequencing question (does post_bond need activate_bond afterward?). The agent must infer the workflow entirely from sibling names.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered; the description adds genuinely new context by naming the pricing model (uw-v1), stating the arithmetic is integer-only, disclosing that slashes can cause outright decline, and explaining that the returned quote_hash lets any party recompute and verify. It stops short of error behavior or limits, keeping it at 4 rather than 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?

The core pricing purpose and the rate drivers are front-loaded, and the parenthetical is efficient. 'Pure — never mutates bond state' duplicates the readOnlyHint, and leading with 'Underwrite' before clarifying this is only a quote creates a brief ambiguity about whether the tool commits anything.

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

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

An output schema exists, so return values need no explanation, and the model/verification story is strong. But for a 7-parameter tool with zero schema descriptions, leaving coverage_minor, duration_days, and slashed_minor unexplained (including units) is a real completeness gap an agent must guess around.

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 only partly succeeds: it explains the directional effect of attestations, successful deliveries, bonds_completed, and slashes, but says nothing about coverage_minor, duration_days, or slashed_minor, and never explains the 'minor' unit convention. Useful meaning is added for about half the inputs.

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 — it produces a deterministic actuarial premium quote for a surety bond from a counterparty's track record — and distinguishes itself from write-oriented siblings (post_bond, activate_bond, slash_bond) by clarifying it is a quote computation. An agent can tell it is a pricing/underwriting call rather than a state-changing bond operation.

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 the rate moves (attestations, deliveries, completed bonds lower it; slashes raise or decline) but never states when to call this versus verify_audit or bond_status, nor whether it is a prerequisite to post_bond. 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: the precondition that open claims block the release, and what actually moves (remaining stake to the principal) rather than relying on the vague name 'release'.

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?

One sentence, front-loaded with the verb and resource, with the failure condition appended after the core action. No redundant restatement of the title 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?

An output schema exists, so return values needn't be explained, and the safety profile is carried by annotations. The description covers the action plus the blocking condition; only finer details (irreversibility of the transfer, any authorization requirements) are absent, which is acceptable for a one-parameter mutation.

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

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

Schema description coverage is 0% and the single parameter bond_id is undocumented in both schema and description. 'bond_id' is fairly self-descriptive, but the description adds no meaning about format, source, or lookup — nothing an agent couldn't infer from the name alone.

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

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

States a specific verb and resource ('Release the remaining stake to the principal') with a precise triggering condition ('after the coverage window elapses'), which cleanly separates it from siblings like slash_bond, post_bond, and activate_bond.

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

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

Gives an explicit when-not condition ('refused while any claim is still open') and a timing prerequisite, so the agent knows when the call will fail. It doesn't route to an alternative sibling (e.g., file_claim or bond_status) when the condition isn't met, which keeps it short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the danger is known; the description adds non-obvious behavior beyond that — a ruling pays at most once, and payout is capped by the bond's available balance so over-claims exhaust the bond. It does not disclose authorization requirements or what the caller receives back, but the payout semantics are a meaningful addition.

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 compact clauses, front-loaded with the action, then the precondition, then the payout constraint. No filler and no restatement of the title 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?

An output schema exists, so return values need no explanation, and the destructive nature is well covered. The remaining gap is call-correctness: an agent cannot determine from this text what setting "upheld" to false does, which matters for a tool that irreversibly slashes a bond's balance.

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 parameter burden; it does explain the provenance and meaning of ruling_case_id and ruling_hash, and links bond_id indirectly via "the bond's available balance." However, the outcome-determining "upheld" boolean (default true) and the distinction between bond_id and claim_id are left entirely unexplained.

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: "Execute an arbitration ruling against a claim." That is clearly distinguishable from siblings such as release_bond, activate_bond, and post_bond, which operate on the bond lifecycle rather than on an arbitration outcome.

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?

"Requires the ruling's case id + content hash from agent-arbitration — no ruling, no slash" gives an explicit precondition and implicit timing (only after arbitration has ruled). It stops short of naming alternatives (for example, when to use release_bond instead) or stating who is authorized to slash.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description contributes the useful fact that the target is a hash chain (implying integrity checking rather than a simple status read), but says nothing about what happens when the chain fails validation or how expensive the check is.

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?

One front-loaded sentence with no filler, and the key differentiator (tamper-evident hash chain) appears immediately. It is efficient, though arguably too terse to stand alone as a complete definition.

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

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

The tool is simple (one read-only parameter) and has an output schema plus rich annotations, so return values and safety need not be explained. Still, the definition leaves the agent without any cue about when to invoke verification or how to interpret a negative result, which is a meaningful gap for a verification 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 0% and the single required parameter bond_id has no title beyond 'Bond Id' and no explanation. The phrase 'for a bond' weakly implies bond_id selects the bond, but the description adds no format, source, or failure semantics for that identifier.

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 pairs a specific verb ('Validate') with a specific resource ('tamper-evident audit hash chain') scoped to 'a bond', which no sibling tool (activate_bond, list_bonds, slash_bond, etc.) duplicates. It is unambiguous what the tool does, though it does not name a sibling or explicitly contrast itself with bond_status.

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

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

There is no guidance on when to run this verification, whether it should be called before/after a state-changing operation such as release_bond or slash_bond, or whether it is cheap enough to call routinely. The only usage signal is the implicit 'for a bond' scope.

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