tersign

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly lists side effects—writes a verdict, may create a refund record—and additional traits like deterministic outcome, public recomputability, first-verdict-wins semantics, and the ledger signature in the return 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?

Three dense sentences front-load the core action, then cover side effects and return values. Every sentence adds necessary information with no redundant or filler 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?

Given one parameter, no output schema, and no annotations, the description is remarkably complete: it covers preconditions, side effects, idempotency, determinism, and return shape. An agent has enough context to invoke the tool correctly and anticipate 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 description coverage is 100% with a single well-documented parameter including format and provenance ('as returned by open_dispute'). The tool description doesn't add further parameter-level semantics, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Trigger deterministic adjudication of an open dispute.' It also distinguishes the tool through deterministic rulebook language and 'no discretion, no model in the loop,' clearly separating it from related dispute workflow tools like open_dispute and get_dispute.

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

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

The description gives clear context: it applies to an 'open dispute' and warns that 'adjudicating twice is not meaningful; the first verdict stands.' It does not explicitly name alternatives or when-not-to-use relative to sibling tools, but the precondition and idempotency warning provide solid usage guidance.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden and does so well. It explicitly states 'Read-only — one network read, no key required, and safe to poll while a dispute is open', giving agents clear expectations about side effects, authentication, cost, and polling safety.

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 with zero filler. The first sentence front-loads the purpose and return contents; the second delivers the behavioral caveats. Every sentence earns its place.

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

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

For a simple single-parameter fetch tool with no output schema, the description is complete: it explains what the response contains, that the call is read-only and cheap, and that polling is safe. No critical operational detail 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 parameter disputeDigest is already fully documented in the schema, including format and provenance ('as returned by open_dispute'). The tool description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Fetch') and resource ('a dispute in full'), and enumerates what is returned: state, both sides' evidence references, verdict and rationale, and ledger signature. It clearly distinguishes itself from the dispute-mutation siblings by emphasizing read-only access.

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

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

The description gives clear context for when the tool is appropriate: it is a read-only fetch, requires no key, and is safe to poll while a dispute is open. It does not explicitly say 'use this instead of X', but the read-only framing makes the correct use case obvious relative to sibling tools like open_dispute and adjudicate_dispute.

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

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

With no annotations at all, the description carries full responsibility. It clearly discloses signing side effects (TERSIGN_SELLER_KEY), conditional network writes, local-signing fallback, and the returned artifact's unchained state. It does not disclose whether the 'ONE network write' is idempotent or reversible, but it covers the major side effects well for a signing/ledger 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 dense but well-structured: purpose, usage rule, side effects, and return value are presented in a logical order. Every sentence contributes value, though the first sentence is long and packs several distinct facts. It is appropriately sized for a complex tool with nine parameters and no 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?

For a nine-parameter tool with no output schema and no annotations, the description covers the core distinction, side effects, and return values. It lacks explicit return value structure or error cases, but the description does list the returned digest and ledger signature. Minor gaps remain around error behavior and exact configuration requirements, but it is stronger than typical tool descriptions.

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 already has a schema description. The tool description adds marginal semantics by explaining why settledAt should be set explicitly for back-filling and by clarifying that taxScheme is recorded but never computed. These are useful but not extensive, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Issue') and a precise resource ('an x402 offer-receipt (EIP-712) plus a Tersign action record'), then immediately scopes it to already-settled payments. It distinguishes itself from record_disclosure by naming it and stating the alternative use case, so an agent can disambiguate without opening the 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 description explicitly states when to use this tool ('Use this for money that moved') and explicitly names the alternative ('use record_disclosure for a non-payment agent action'). It also describes configuration-dependent behavior for ledger wiring, which tells the agent under what conditions chaining occurs.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It usefully discloses the payer-key prerequisite, the three grounds, and the different adjudication paths (arbiter vs. instant ledger arithmetic). It does not mention post-submission effects or reversibility, but the core behavioral traits are well covered.

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 with no filler. The purpose and role are front-loaded, followed by reasons and behavioral outcome. Every sentence contributes information an agent needs before invoking the tool.

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

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

The description adequately covers who can call the tool (payer), the permitted reasons, and what happens after submission (arbiter or instant decision). With no output schema and no annotations, it would benefit from a note on side effects or dispute lifecycle, but the core calling context is present and sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the reason enum values but adds no new parameter-specific meaning; the schema already documents receiptDigest, claimAmount, statement, and each reason in detail.

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 ('Open'), a specific resource ('dispute against a counter-signed receipt'), and the required role ('as the PAYER'). The enumeration of reasons and escalation behavior clearly distinguishes it from sibling tools like submit_dispute_evidence and adjudicate_dispute.

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

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

Provides clear context: only the receipt payer can open, and the three allowed reasons are enumerated. It also clarifies that non-mechanical claims escalate to the arbiter while duplicate_charge is instant, which helps an agent decide when this tool is appropriate. It does not explicitly state when to use alternatives like submit_dispute_evidence or adjudicate_dispute, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses local digesting, signing with the caller's key, public-ledger counter-signing, per-signer hash chains, and free self-provisioning. It does not explicitly state irreversibility or post-record behavior, but the public-ledger and hash-chain wording makes the durable write intent clear.

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 no filler: the first states purpose and mechanism, the second adds the key onboarding fact. Important details such as local processing and no API key are 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?

Given six parameters, no output schema, and no annotations, the description plus schema cover the workflow, onboarding, and key parameter semantics. The main gap is an explicit return/result description, though the schema's chainId note partially covers what the first call produces.

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

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

The schema already documents most parameters, so the baseline is 3; the description adds useful cross-cutting meaning by mapping 'digests the disclosure text LOCALLY' to text/textDigest, 'signs an action record with your key' to signingKey, and 'per-signer hash chain' to agentId/chainId. It does not enumerate every parameter, but the schema fills those details.

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 concrete action and resource: recording one-call disclosure evidence under the EU AI Act Art 50, with a clear mechanism (local digest, signing, public-ledger counter-signing). This is distinct from sibling tools like record_refund and verify_compliance_record, so an agent can identify the tool's purpose without ambiguity.

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

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

It provides a clear when-to-use context: when EU AI Act Art 50 disclosure evidence is needed, and it stresses a one-call, no-API-key flow. It does not explicitly enumerate when not to use it or name sibling alternatives, but the regulatory use case is specific enough to route the 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?

With no annotations provided, the description carries the full burden, and it delivers: it discloses append-only immutability ('nothing is edited or deleted'), the network write side effect, environment prerequisites, the error condition for a missing original digest, and the semantic limitation that it moves no money. This is exemplary behavioral disclosure.

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

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

Four sentences, each carrying distinct value: role/purpose, chain semantics, requirements/error behavior, and semantic boundary/return values. There is no filler, though the description is slightly longer than strictly necessary; it remains well-structured 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?

Given no output schema and no annotations, the description is unusually complete: it states prerequisites (ledger config), side effect (one network write), error condition (digest not on chain), role constraint, and return values (record, digest, counter-signature, sequence number). An agent has what it needs to invoke the tool correctly without digging elsewhere.

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 documents all three parameters with 100% coverage, including amount as a precision-preserving decimal string, reason as verbatim text, and originalDigest with regex pattern and existence requirement. The description adds essentially no new parameter-level meaning beyond what the schema states (e.g., original digest must exist), so a baseline 3 is appropriate.

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

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

The description opens with 'Record a refund against an already-chained receipt, as the SELLER', stating a specific action, target resource, and role. It clearly distinguishes this from issue_receipt and other tools by focusing on refunds of already-chained receipts and explicitly noting it records an already-made refund rather than creating the original charge.

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

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

The description gives clear context: use this when you are the seller and have already made a refund, and you need to record it against an existing receipt. It also clarifies a boundary ('moves no money') and a prerequisite (ledger configuration). It does not explicitly name alternative tools or list when-not-to-use conditions, so it falls just 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?

With no annotations, the description carries the full behavioral disclosure burden. It usefully reveals signing requirements and the respondent's additional TERSIGN_LEDGER_API_KEY need, but it does not mention side effects, whether submissions can be amended, idempotency, or what happens once evidence is accepted.

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 with no fluff. The core action is front-loaded, and the additional key-requirement detail is compact but essential.

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 input schema is rich and covers parameters thoroughly, but there is no output schema and no description of the response, submission lifecycle, or whether multiple submissions are allowed. For a write-style tool with no annotations, an agent still lacks closure on what happens after the 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 description coverage is 100%, so the schema already documents parameters, but the description still adds value beyond it. It ties the 'role' enum to concrete key requirements and clarifies what 'signed evidence' means operationally, which directly informs correct parameter selection.

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 starts with a specific verb and object — 'Submit signed evidence' — and qualifies it with 'to an open dispute,' making the tool's role unmistakable. This clearly distinguishes it from sibling tools like open_dispute, get_dispute, and adjudicate_dispute.

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 'open dispute' provides clear context for when this tool is appropriate, and the role distinction explains the two filing sides. However, it does not explicitly name alternatives or state when not to use it, such as before a dispute is opened or after adjudication.

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

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

With no annotations available, the description carries the full burden and does so thoroughly. It discloses that the operation is fully offline with no network/API key/account, that PASS proves only integrity and internal consistency, and that authorship requires an out-of-band signer. It also specifies the return shape and mismatch 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?

Every sentence earns its place. The description front-loads the core purpose, then adds offline behavior, sibling routing, an important limitation, and the return format. It is dense but not bloated, with no redundant phrases.

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

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

Despite having nested object parameters, no output schema, and no annotations, the description fully equips an agent to call the tool correctly. It covers parameter handling, return values, failure behavior, offline constraints, and the distinction from the similarly named sibling tool verify_receipt.

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

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

Although schema coverage is already 100%, the description adds meaningful parameter semantics: record must be passed as an object not a string, any field edit changes the digest, attestation is the signature returned at issuance, and expectedSigner is optional but enforces authorship. This goes well beyond the schema property descriptions.

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

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

The description opens with a specific verb and resource: 'Verify a Tersign action record against its attestation', and details the mechanism (recompute canonical digest, confirm attestation commits, recover signature). It also distinguishes itself from verify_receipt, making its scope unmistakable.

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

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

Explicit guidance is provided: 'Use this for an action record... use verify_receipt for a payment receipt.' It also tells the caller when to pass expectedSigner versus omit it, and warns that PASS only proves integrity, not authorship without an out-of-band signer address.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses fully OFFLINE operation, no network/API key/account requirement, the return shape { valid, signer, digest }, and the specific behavior when expectedSigner mismatches. This exceeds what an agent could infer from the schema alone.

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

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

Three tightly packed sentences: the first states the core operation, the second adds offline constraints and the intended user, and the third covers routing and return behavior. No filler or repetition of schema content, and the most critical details are 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?

Given no output schema and no annotations, the description provides all essential context: purpose, offline behavior, sibling differentiation, expectedSigner guidance, and return values. The nested artifact parameter is sufficiently described in the schema, and description-schema combined coverage leaves no critical gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic detail beyond the schema. It clarifies the expectedSigner behavior in the mismatch case and reinforces the artifact as an object, not a string, which helps avoid common invocation errors.

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: 'Verify an offer-receipt artifact' with a clear mechanism ('recover the EIP-712 signature and confirm the payload digest binds to it'). It also distinguishes itself from the sibling verify_compliance_record by domain, leaving no ambiguity about which tool handles receipts.

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 when to use this tool versus the alternative: 'Use this for a receipt (money); use verify_compliance_record for an action record (a non-payment action).' It also emphasizes the offline, no-account nature and that verifying someone else's receipt is the intended use, which guides selection.

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