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

With no annotations, the description carries the full burden and discloses key behavior: a sponsor pays the fee, the call waits about 1–2 minutes, the first call downloads prover keys, and only the hash and metadata hash go on-chain while the document stays local. It also clarifies ownership via caller seed and that retrying with the same arguments resumes the existing job without submitting a new one.

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 primary action and keeps every sentence informative: timing, cost sponsor, prover key download, on-chain data limits, return shape, and retry semantics all earn their place. No repetitive or purely decorative text.

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 supplies the return shape and explicitly notes that check is the verify_attestation call that shows the record on-chain. It also covers dependencies, defaults, retry behavior, and on-chain data boundaries, leaving little an agent needs to infer before calling.

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 meaning beyond the schema by explaining that sha256 becomes payloadHash, metadata is hashed on-chain, contentRoot and schemaId come from prepare_document_proof and feed submit_vault_call, and contractAddress defaults to the shared sandbox vault. It could say more about idempotencyKey and compiledArtifactRef beyond the schema, but the interdependencies are useful.

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 — anchor a document hash on Midnight — and describes the one-call workflow, including building the attest transaction, sponsorship, and waiting for landing. It differentiates from siblings by naming prepare_document_proof, submit_vault_call, and verify_attestation in their respective roles.

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 the primary use case and the optional path when contentRoot and schemaId from prepare_document_proof are supplied. It also gives explicit retry guidance for cut-off or pending calls. It does not spell out when not to use this tool, 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?

With no annotations, the description carries the full burden and does: nothing secret leaves the machine, the seed stays local, the fee-unpaid tx is held in-process under txId (its sha256) or written to outFile, proving takes 20-60 s with a first-call /zk-config key fetch, NIGHTGATE_PROOF_SERVER_URL switches to a proof server, and the @odatano/nightgate-tx dependency is declared. The TTL (~30 min) and build-time-state caveat are exactly the operational facts an agent needs before spending a minute on a proof.

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?

Nearly every clause earns its place, but it is delivered as one dense semicolon-chained paragraph rather than front-loaded sections, so the per-call param catalog and the ZK-claim addressing rules are hard to scan. A few facts are duplicated from the schema (bind, contractAddress default). Appropriate length for the complexity, poor structure.

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

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

Covers the operation, the secrecy model, output handling, downstream hand-off, timing, dependencies, error recovery, and return values (txId as sha256, the returned attester id) despite no output schema. For an 8-param, nested-object, multi-circuit tool with no annotations, nothing material 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%, so baseline is 3, but the description adds semantics the schema does not carry: the schema defers to the description for per-call params, and the description supplies the full per-circuit param list plus the three record-addressing modes (payloadHash, payloadHash+attesterId, recordKey) and the recordKey(attesterId, payloadHash) derivation rule. That is substantive value beyond the structured fields.

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 compound verb+resource: build, prove and sign an AttestationVault call locally and return the bytes. It immediately distinguishes itself from the sibling that does build+submit in one go (submit_vault_call), so an agent can route without opening either 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?

Explicitly names the alternative (submit_vault_call) and the condition that selects it, then routes onward by output mode: sponsor_unbound_transaction by default, sponsor_finalized_transaction with bind:true. It also names prepare_document_proof as the source of every witness field and gives a retry rule (rebuild if the sponsor job ends CHAIN_EXECUTION_FAILED).

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 so: it discloses that a sponsor pays the fee and this call spends none, that coins stay reserved until the swap lands, that the first taker consumes the offer, that offers expire with chain state, and even proving latency (200 s in-process vs 11–17 s on a proof server). That is exactly the operational context an agent needs before committing a wallet.

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?

Roughly 150 words, but front-loaded with the mental model of a two-half swap before the call-specific details, and the length is justified by fee, reservation, expiry, and latency disclosures. A few clauses (e.g. the mirrored-halves explanation) could be tightened, but nothing is 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 fully covers the return values (offer file, id, read-back terms) plus the operational lifecycle an agent must reason about: reservation, expiry, consumption by the first taker, and the fee model. Nothing material for correct invocation 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 only 33%, but the description compensates by giving directional meaning to give and want (what this wallet spends vs what it wants) and a hard constraint on give.amount tied to get_swap_wallet's spendable. It also clarifies the shape of the return (offer text prefixed swapoffer1, ~25 000 chars, id, terms). The bind flag's distinction is left to the schema's own 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?

States a specific verb+resource: it 'builds and proves ONE half' of a swap from this server's wallet, spending `give` and creating `want`. It explicitly scopes itself against the mirrored half and the taker side, so an agent can distinguish it from take_swap_offer, sponsor_swap, and build_sponsorable_transaction without opening a 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?

Gives concrete when-to-use context (publish promptly because the offer expires with chain state; anyone holding the wanted token can take it) and names the counter-action (revert_swap_offer) for offers that won't be used. It also states the precondition that give.amount may not exceed spendable from get_swap_wallet. It stops short of an explicit comparison against the sibling build/sponsor tools, so it is clear but not fully routing.

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 burden and does so well: it discloses the supply-ledger mutation, sponsor-pays model, prerequisite lists, roughly one-minute settlement wait, return shape, and idempotent retry 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?

The description is front-loaded with the action and effect, then covers prerequisites, return value, and retry handling. It is dense and appropriately sized for the complexity, though the long compound sentences reduce readability slightly.

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 a mutation tool with no annotations and no output schema, the description supplies the effect, sponsorship requirements, async settlement behavior, return fields, failure guidance, and retry instructions. Nothing critical for correct invocation appears 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%, so parameters are already documented. The description adds some nuance around issuerKey defaulting to a wallet-minted token and retry behavior for idempotencyKey, but most parameter meaning is already in the schema, making the baseline 3 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 verb and resource: burn a factory token this wallet holds, with the effect that coins leave circulation and the factory supply ledger drops. This clearly distinguishes it from siblings such as mint_token and send_token.

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 conditions: the factory must be on the sponsor's contract list and burn on its circuit list, and issuerKey defaults to a token this wallet minted. It does not explicitly name alternatives or exclusions such as send_token, 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: it discloses that the call is built, proven and signed server-side from the caller seed with a sponsor paying, so the caller needs neither NIGHT nor DUST; that a $coin call is bound and goes through the serial sponsor channel versus the parallel one otherwise; the env vars and ~20 s / ~5 min sync waits; and the ~1 minute settle time. That is unusually rich disclosure of cost, auth, latency and channel side effects.

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 action, then prerequisites, then timing, then retry semantics — a sensible order. It is one dense paragraph with stacked parentheticals (sync waits, env vars) that could be split, but nearly every clause carries operational 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?

No output schema exists, yet the description names the return shape { status, txHash, transactionHash, result } and points to `next` on failure. Combined with prerequisites, wallet/env requirements, channel behavior and retry idempotency, an agent has everything needed to call and recover it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond it: arguments are JSON in circuit order, and tagged values are spelled out ({"$bytes"}, {"$uint"}, {"$coin" with tokenType/amount), including that a $coin is funded from this wallet — the one get_swap_wallet shows. That materially changes how an agent constructs the args array.

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 — call a circuit of a deployed contract — and scopes it precisely to lineage packages installed beside the server, with the expected layout (@odatano/contract-<name> with contract.json, compiled class, proving files). That scope distinguishes it from generic build/sponsor siblings like build_sponsorable_transaction or submit_vault_call without the agent needing 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?

Gives clear preconditions (contract must be on the sponsor's policy; circuits needing extra witnesses are not reachable here) and explicit retry guidance: re-run with the same arguments if the call was cut off or pending, since it resumes the existing job. It never names a sibling alternative such as submit_vault_call, so the when-not-this-tool routing 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?

With no annotations, the description carries the burden and does well: it explicitly discloses that the operation is compute-only with no wallet or chain access, and describes how the output is consumed downstream. It stops short of stating failure modes or validation behavior for bad domain separators or addresses.

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 dense sentences, front-loaded with purpose and followed by parameter meaning and downstream use; every sentence carries information. The jargon-heavy phrasing ('rawTokenType(domainSeparator, contractAddress)', 'Compact pad(32, ...)') is slightly compressed but not wasteful.

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 crypto utility with no output schema, the description covers purpose, safety profile, parameter formats, defaults, and downstream consumption, which is everything an agent needs to call it correctly and use its result.

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, and the description adds genuine semantic value: it explains that domainSeparator is the plain string the contract pads (Compact pad(32, ...)) or 64 hex, and that it defaults to the bundled test token's value. This goes beyond the schema's terser wording by explaining how the separator is used.

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 ('Derive the raw token type a minting contract produces') and immediately scopes the nature of the operation with '(compute-only, no wallet, no chain access)'. This clearly distinguishes it from siblings like mint_token and sendNight, so an agent can select it 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?

Explains why and when to call it: 'without it the minted balance cannot be transferred', and where the result goes ('feeds sendNight(tokenTypeHex)'). It gives strong context but does not name explicit alternatives or when-not-to-use conditions, so it falls just short of the top tier.

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 meaningful work: it discloses the id is deterministically derived from the caller seed via the txbuilder, and that the call is side-effect free ('builds nothing and submits nothing'). It omits whether the shielded keys are stable across calls or any auth/caching behavior, so it falls short of exhaustive.

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 the return contents front-loaded and the usage hint last; no filler. The nested parentheses around the derivation and the sender rationale make it slightly harder to parse than necessary, but every clause 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 zero-param, no-annotation, no-output-schema read tool, the description enumerates the returned fields, the derivation source, and the non-mutating guarantee — enough to call it correctly. What is left unexplained is where the caller seed comes from and whether the keys can change, which are secondary for 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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The implicit inputs (caller seed) are explained in the context of the derived output rather than as callable parameters.

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 concrete verb+resource: returns the attester id this server builds under, plus network, shielded address and two public shielded keys. It also implicitly separates itself from verify_attestation, which checks attestations rather than reporting the identity. An agent can tell exactly what it gets back 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?

Gives an explicit trigger: 'Use it to check verify_attestation results against the identity that will appear on-chain', naming the sibling it complements. It does not spell out when NOT to use it, but the closing 'builds nothing and submits nothing' removes the main ambiguity for an agent deciding between it and build/sponsor 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?

With no annotations, the description carries the full burden and does well: it discloses that no credentials are required, that results are computed at most every 10 seconds, and what one key field means for downstream sponsor_swap behavior. It does not explicitly describe side effects, but the counts framing strongly implies a read-only status operation.

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 that identifies the resource, access requirement, returned fields, key interpretation, and freshness. Every clause adds useful information 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?

There is no output schema, so the description must explain the return values, and it lists the fields and clarifies the important ones such as sponsorsReady and asOf freshness. It does not specify field types or the exact response envelope, but it is otherwise complete for a simple status tool.

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

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

The tool has zero parameters, so the baseline score is 4 according to the rules. The description focuses instead on return fields, which is appropriate for a parameterless status tool.

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: it returns counts for the server's offer board and sponsors. It also lists the exact metrics returned, so an agent can distinguish this status-reading tool from siblings like list_swap_offers, take_swap_offer, or sponsor_swap.

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

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

The description provides clear context for use: no credentials are needed, and a sponsorsReady value of 0 means a sponsor_swap would wait or fail now. It does not explicitly name alternatives or when not to use this tool, but the readiness signal gives practical 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, the description carries the load and does so well: it discloses the 404 on unknown id, that filledTxHash only appears once a swap has spent the offer, and that the poster and the half's nullifiers are never returned (a meaningful privacy constraint). It omits auth or rate-limit expectations, 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?

Front-loaded with the core purpose and dense with earned detail; almost no waste. The phrase 'Each row' is slightly off for a single-object getter and creates a small moment of confusion about whether the result is an array.

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 and no annotations, the description must describe the return shape, and it enumerates every field plus the error case and privacy exclusions. Missing only environment-level facts like auth requirements, which is beyond most agents' immediate need for a read getter.

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, offerId, and the schema already documents it at 100% coverage including uuid format and pattern. The description adds marginal meaning by framing the returned offer half as input for read_swap_offer or take_swap_offer, but nothing beyond the schema about the id itself.

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 ('One board offer by id'), scopes it to open-or-closed, and distinguishes it from read_swap_offer/take_swap_offer by noting the returned offer half is what those tools consume. An agent can tell it apart from list_swap_offers, my_swap_offers, and read_swap_offer 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?

Gives concrete context: 'The way to follow an offer after post_swap_offer or after taking one,' which ties it to specific sibling tools and lifecycle moments. It does not explicitly say when to prefer list_swap_offers or read_swap_offer instead, so the routing is implied rather than spelled out.

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 burden and does so well: it states that the tool spends nothing, syncs only shielded coins, may take about five minutes on first genesis sync, returns a { synced: false, syncingSeconds } interim shape, and explains how pending and spent halves affect the reported wallet 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?

The description is front-loaded with the core resource and return fields, and most clauses carry domain-relevant meaning. However, it is a dense, run-on paragraph with heavy jargon and nested conditionals that make it harder to parse than necessary.

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 zero parameters, no output schema, and no annotations, the description does substantial work: it describes the wallet contents, pending versus balance semantics, the unhanded swap-half list, and the syncing interim response. It is nearly complete for an agent to understand what it will get and how to react to sync-in-progress.

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 there are no call-site parameters to explain. The description appropriately focuses on the returned data and state semantics instead.

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

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

The description clearly identifies the resource as the shielded wallet used by the MCP server and enumerates the key data it returns: address, public keys, per-token balances, spendable amounts, pending amounts, and unhanded swap halves. It also names related siblings like revert_swap_offer and post_swap_offer, though it does not directly contrast with get_swap_offer or list_swap_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?

Usage is implied through statements about the wallet's pending/balance semantics and the instruction to call again when syncing, but there is no explicit guidance on when to call this versus sibling tools such as get_swap_offer or list_swap_offers. The context suggests it is an inspection endpoint, but alternatives and exclusions are not spelled out.

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 so well: it discloses that the call is free, explains the two auth modes and their different payloads, and mentions the retryAfterSeconds context after a 429. It does not describe pagination or bounds on the 'last calls' ledger, keeping it below 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 description is a single dense paragraph that is front-loaded with purpose, then mode-specific return details, then usage guidance. Every sentence earns its place, though the density and parenthetical clauses make it slightly harder to scan than it could be.

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

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

For a dual-mode tool with no output schema and no annotations, the description is largely complete: it explains what each credential type returns and when to call it. Missing details such as how many recent calls are included in the ledger are minor but prevent a 5.

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

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

Schema coverage is 100%, and the schema already documents that since/until are agent-grant-only window bounds defaulting to 30 days back. The description mentions the 30-day view but adds no syntax or usage details 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 opening sentence states the resource precisely: remaining balance and spend for the current key. It then distinguishes the two credential modes (gateway key vs. agent grant) with concrete returned fields, so an agent knows exactly what this tool does.

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

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

It gives explicit timing guidance: 'Read it before a burst and after a 429'. That covers the primary when-to-use contexts. It does not name alternatives or exclusions, but no sibling tool provides similar usage data, so the gap is minor.

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 burden and does so well: it documents ordering, waitMs holding behavior, version requirement, read authorization, returned row fields, and privacy exclusions. These are exactly the operational details 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?

The description is front-loaded with default behavior and every clause adds operational detail, including a useful row-field list because there is no output schema. It is somewhat dense and semicolon-heavy, which reduces readability slightly.

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 seven optional parameters, no output schema, and no annotations, the description is complete enough to call the tool correctly. It explains return fields, privacy exclusions, mode interactions, and the long-poll behavior.

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 semantics for status, since, waitMs, and exact filter constraints. The limit parameter is left to the schema, but overall the description adds substantial 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 resource (offers on the server's board) and the main modes (open default, closed statuses, change feed). It does not explicitly name `my_swap_offers` as the sibling for the caller's own offers, so sibling differentiation is mostly implicit.

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

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

It gives concrete selection rules: no status means open offers; status filled/retired/expired/all reads closed offers; status all plus since polled repeatedly becomes the change feed; waitMs enables long-poll watching. It also explains that the offer half should be fed to read_swap_offer or take_swap_offer.

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: it discloses that the issuer secret derives from the caller seed and never leaves the process, that a sponsor pays, that the call blocks until settlement (~1 minute), the returned shape { status, txHash, transactionHash, result }, that failure carries a `next` hint, and that retries are idempotent and will not double-submit.

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, then prerequisites, return shape, and retry guidance in a logical order; nearly every sentence earns its place. The prose is dense and a couple of clauses (e.g. the inline `next` reference) are terse to the point of mild ambiguity.

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 6-parameter mutation with no annotations and no output schema, the description covers preconditions, side effects, blocking behavior, return keys, and recovery. The remaining gap is that `result` and `domain`/`issuerKey` are named but never explained, leaving the agent to infer their contents.

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 still adds value by stating that the recipient defaults to this wallet (via get_attester_identity) and that a third-party recipient requires both of its keys. It does not expand on `amount` atom semantics or `idempotencyKey` 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+resource ('Mint a shielded token ... on a token-factory deployment') and immediately disambiguates identity semantics ('The same name from another issuer is another token'). An agent can distinguish this from derive_token_type or the swap siblings without opening a 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?

Gives concrete preconditions for use (factory must be on the sponsor's contract list, mint on its circuit list) and a recovery path (re-run with the same arguments if cut off or pending). It does not explicitly name which sibling to use instead for related tasks, so it stops 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 burden and discloses ordering by last change, open/closed states, since filtering, waitMs waiting behavior, returned row fields, and exclusions. It does not explicitly state read-only status or auth requirements beyond the caller/grant scope, but it provides strong 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 core purpose and scope are front-loaded, and most sentences carry useful detail. It is dense and somewhat run-on, but appropriately sized for the tool's complexity.

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

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

There is no output schema and no annotations, so the description must explain behavior and returns; it does both by listing the row fields, ordering, filtering, wait semantics, and exclusions. An agent has enough information to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics for status, since, and waitMs beyond the schema. It does not add meaning for limit, which is documented only by 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+resource: it lists offers this caller posted on the board, with open/closed scope and ordering. It is clear, though it does not explicitly distinguish itself from the sibling list_swap_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 caller-scoped context is clear, and it tells the agent to feed each row's offer half into read_swap_offer or take_swap_offer. It does not explicitly name when to use list_swap_offers instead, but the usage context is well established.

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 so: it discloses validation rules (one token given, one wanted, both on the server's list, never NIGHT), closure conditions (spending an input, expiry, retire_swap_offer), the auth requirement (postSwapOffer in allowedActions), the return shape, and that takerSecret is shown once. This is unusually rich behavioral context.

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

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

Dense but front-loaded: the primary action and board-visibility rationale lead, followed by validation, lifecycle, auth, and return value. The directed clause is a long trailing sentence, but each sentence carries distinct information and nothing is padding.

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

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

No output schema exists, yet the description states the return object ({ offerId, status, terms }). Auth, validation, closure, and version prerequisites are all present, so an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning beyond the schema for 'directed' (secret gate, hand to counterparty, shown once, NIGHTGATE 0.39.0 requirement) and confirms where tags surface (list_swap_offers). It does not add syntax detail for offer or expiresAt, but the schema covers those well.

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 ('Post a maker half on the server's offer board') and immediately distinguishes it from out-of-band delivery and from list_swap_offers. An agent can tell it apart from build_swap_offer, take_swap_offer, and retire_swap_offer without opening a 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?

Explicitly frames the when ('so takers find it with list_swap_offers instead of receiving the offer file out of band') and names the lifecycle alternative (retire_swap_offer closes it). The directed parameter is scoped to invoice/agreed OTC use, giving concrete selection criteria.

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 present, the description carries the full behavioral burden and does so well: compute-only, synchronous, nothing stored server-side, salted leaves, returned witness material treated as sensitive, and a strong warning that losing the salt seed makes the anchored root unprovable while publishing it makes leaf hashes guessable. It also discloses the re-serialization caveat for canonicalDocument.

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

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

The description is dense and lengthy, but the core purpose is front-loaded before the operational caveats. The length is justified by the cryptographic and storage risks being communicated, though the single-paragraph structure could be easier to scan with clearer separation of input guidance, output artifacts, and storage requirements.

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 complex, nested, no-output-schema tool, and the description still explains the returned artifacts (payloadHash, contentRoot, inclusion paths, salt, opening, schemaId), their downstream consumers, storage obligations, sensitivity, and reproducibility via saltSeed. An agent has enough context to invoke it correctly and handle its outputs 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 100%, so the schema already documents document, saltSeed, proofFields, kind, scale, field, and compiledArtifactRef in detail. The prose reinforces the kind and saltSeed semantics and adds that field order is part of the tree identity, but most parameter meaning is already in the schema, making 3 the appropriate baseline.

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

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

The description opens with a specific verb and resource: "Turn a structured document into everything the proof tools need," then enumerates canonical JSON, payloadHash, contentRoot, and inclusion paths. It distinguishes this preparatory tool from anchor_document and submit_vault_call by naming both and explaining what each downstream step consumes.

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

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

It clearly positions the tool as a pre-anchoring/pre-proof preparation step and names the siblings that consume its output. It also gives a concrete when-to-use rule for saltSeed: pass it to reproduce an existing anchored root, omit it for a fresh document. It stops short of explicit "do not use this when..." guidance or a full decision tree among 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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses the deterministic construction rule, compute-only synchronous behavior, sensitive witness material, and a clean 400 for non-members. No annotation contradiction is present.

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 action and remains tight despite covering algorithm, downstream use, optional witness behavior, and error semantics. Every sentence contributes useful context.

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 compute-only tool with no output schema and no annotations, it provides enough behavioral and usage context to call it correctly. It could be slightly more complete about the exact return shape beyond setRoot and inclusion path, but the essential semantics are covered.

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 schema already documents all parameters. The description still adds useful semantics for value/valueDigest as inclusion-path inputs and for allowedValues as the public allow-list, though it does not add meaning for compiledArtifactRef.

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: 'Build the canonical depth-6 membership-set tree over a public allow-list.' It also clarifies the downstream relationship to verify_predicate, so an agent can distinguish this preparation tool from the verification sibling.

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

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

It clearly says to use the resulting root to verify_predicate a setMembership claim, and explains the optional value/valueDigest path. It does not explicitly state when not to use it or name competing alternatives beyond verify_predicate.

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 whole burden and does well: it says no wallet or network is needed, enumerates exactly what is read (gives/wants, coins carried, bound status), and discloses refusal conditions (contract call, unshielded value, multiple token types). It stops short of describing error reporting or whether the carried transaction's cryptographic proofs are validated.

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 capability is front-loaded and most sentences earn their place. The opening explanation of how a swap half is constructed is useful background for understanding the trust model, but it makes the paragraph longer than strictly necessary for selecting 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?

For a domain-specific, complex tool with no output schema, the description gives a strong operational picture: what is parsed, what makes input invalid, side-effect freedom, and the natural next step. It is slightly incomplete in not naming the exact shape of the returned fields or how proof verification factors in, but an agent has enough to call it correctly.

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

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

The input schema already documents the single 'offer' parameter fully (offer file text or base64 of the serialized, proven transaction). The description reinforces that the offer is read as a transaction, but adds no new syntax or format detail beyond what the schema provides, 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?

States a specific verb (reads) and resource (a swap offer), and explains exactly which facts are extracted from the carried transaction rather than from the maker's claims. It does not explicitly differentiate itself from the sibling get_swap_offer, so an agent must infer the 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?

Gives clear sequencing advice – 'Check the terms here before take_swap_offer' – which tells the agent where this fits relative to the most relevant alternative. It lacks explicit when-not-to-use guidance or a direct contrast with get_swap_offer, but the refusals section implies the tool's boundary.

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 burden and does well: it discloses authorization ('Only its poster may'), the key state effect ('coins behind the half stay reserved'), and the return shape ('Returns { offerId, status }'). It does not explain whether the retirement is permanent, reversible, or what errors may occur, leaving some mutation semantics 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?

The description is compact and front-loaded: the first sentence states the core action, followed by the authorization rule, state effect, sibling reference, and return shape. Every clause contributes useful context with no wasted language.

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 mutation tool with no annotations and no output schema, the description supplies the essential context: who may invoke it, what happens to reserved coins, and what fields are returned. It is slightly incomplete about permanence and error behavior, but otherwise sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the offerId parameter is already fully documented in the schema. The description refers to the offer and its poster but adds no syntax, format, or constraint details beyond what the schema provides, so the 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 states a specific action on a specific resource: taking a swap offer off the board. It also differentiates from the sibling revert_swap_offer by explaining that retirement leaves reserved coins pending a separate revert step, so an agent can distinguish retire from revert without opening either 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?

It gives clear usage context by stating only the poster may retire an offer, which is an important authorization prerequisite. It also names revert_swap_offer as the follow-up alternative for releasing reserved funds, though it does not explicitly say when to use take_swap_offer or other sibling operations instead.

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 load and does disclose key effects: coins count as spent until the revert or until the swap lands, and a half whose swap landed disappears from get_swap_wallet. It omits what happens if the id is invalid or already landed (error vs. no-op) and whether the call is idempotent.

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 with the action stated first and the state-effect caveat immediately after. The middle sentence ('Until then, or until the swap lands...') is slightly tangled but still earns its space by explaining why a revert is needed at all.

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 and no annotations, so the description must supply the full picture; it covers purpose, state effects, id provenance, and the one important exclusion. Only failure modes and return behavior are left implicit, which is a small gap for a one-parameter 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 0% and the single 'id' parameter is only constrained by a hex pattern, not a description. The description partially compensates by telling the agent where to obtain ids (get_swap_wallet) and that landed halves drop off that list, but it never states the accepted id format or rejects legacy ids.

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 coins of a swap half') and even names the sibling tools that create such halves (build_swap_offer, take_swap_offer), so an agent knows exactly which objects it acts on. It is clearly distinguishable from offer-publishing tools like post_swap_offer.

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 rule: it does not recall an offer someone already holds, and points to spending the coins in another swap instead. What's missing is any differentiation from the sibling retire_swap_offer, which is the most likely tool to confuse with this one.

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: it explains that the transfer is built and proven locally, that only fee-unpaid bytes reach the server, what the server records and submits, the roughly one-minute wait for the block and signed receipt, the null-receipt timeout and how re-calling fetches it, and the settled return shape { status, txHash, transactionHash, result }. That is unusually complete disclosure of side effects, timing and idempotency.

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 purpose is front-loaded and most sentences carry operational information, but the middle section is dense and slightly muddled: two separate 'the tool waits...' explanations (block/receipt vs job settlement, both 'about 1 minute') run together and are hard to reconcile. Tighter separation of the receipt wait from the settlement wait would improve it.

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 naming the return fields and failure handling ('next' says what to do) and by covering auth requirements, server-side behavior, and retry semantics. For a mutation tool with zero annotation coverage, nothing essential to calling 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%, so per the baseline the schema already documents all four parameters. The description adds indirect meaning — the tokenType must be on the sponsor's list, the amount is 'declared' to the server, maxInputs bounds coin selection — but the idempotencyKey and exact amount semantics are left entirely 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?

The description opens with a specific verb, resource and scope: sending a shielded token from this wallet to another shielded address with a sponsor paying the fee, and grounds it with concrete use cases (payout, salary, invoice settlement). It is clearly distinguishable from siblings like burn_token or mint_token.

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?

Prerequisites are spelled out precisely — sponsorTransfer in the grant, the type on the sponsor's list, NIGHTGATE 0.39.0 — and retry behavior is defined for pending or interrupted calls. It stops short of naming a sibling alternative for cases where these conditions fail, so it is clear context without explicit routing.

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 so well: it discloses who pays the dust, which identity the on-chain effect carries, allow-list enforcement, TTL expiration, serial-channel blocking, block-wait behavior, receipt nullability, idempotent resumption, and the return shape. These are material behavioral traits an agent needs before invoking the 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 front-loaded with the essential purpose and scope, and most sentences add distinct value. It is somewhat dense and repeats the wait/retry behavior in two places, but the redundancy is minor rather than confusing.

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 mutation-style tool with no annotations and no output schema, the description is complete enough to call correctly: it covers prerequisites, serial-channel constraints, failure/retry behavior, return shape, and identity implications. Nothing critical 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 meanings are already fully documented in the schema, including the provenance of txId and the caution around finalizedTxB64. The description adds useful context about idempotent retries but does not add meaning beyond the schema for the individual parameters.

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: submit a finalized, fee-unpaid transaction for cross-server fee sponsoring. It explicitly distinguishes this serial path from sponsor_unbound_transaction and from the build step handled by build_sponsorable_transaction.

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

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

It explains when to use this tool (transaction already built, proven, and signed elsewhere), when to use the alternative (parallel submission via bind:false and sponsor_unbound_transaction), and how to behave on retries or pending outcomes. The guidance is explicit and actionable.

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 the full burden and delivers: disabled by default via NIGHTGATE_SPONSOR_ALLOW_SWAPS, the agent grant needs sponsorSwap in allowedActions, an offer fills exactly once so a taken offer fails the job, and the call blocks ~1 minute while waiting for settlement and the signed receipt, with a documented null-receipt recovery path. Validation constraints (allow-list, never NIGHT, ≤4 inputs / 2 outputs per half, mirrored types and amounts) are disclosed up front rather than surfacing as opaque failures.

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 content is dense rather than padded, but it arrives as one long chain of colon-and-semicolon clauses with the most actionable information (which parameter combinations are legal) buried mid-paragraph. The return shape is stated twice in near-duplicate form, and the two separate 'waits about a minute' statements could be one. Front-loading the invocation modes and pushing the swap mechanics to a second paragraph would cost nothing and gain a lot.

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 6-parameter, zero-annotation, no-output-schema mutation tool this is close to complete: return payload, receipt timing, failure signalling via `next`, enablement flag, permission grant, and idempotent retry are all covered. The gaps are small — what `takerSecret` unlocks for directed offers and what a failed job's `next` typically contains are asserted rather than described.

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 earns a step up by explaining the relationships the schema cannot: `halfId` alone names a taken offer but alongside both halves merely ties the job to it, and `offerId` sources the maker half from the board and must be paired with `takerHalf` or the taken half's `halfId`. `takerSecret` and `idempotencyKey` are left to their schema text ('dedupes retries of the SAME two halves'), which is adequate.

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 precisely what happens: two mirrored half-transactions are merged by a sponsor that checks them, pays the fee and submits, so two shielded token types move between wallets without a contract. That is far more specific than the name alone, and it names relatives (take_swap_offer keeps both halves; offerId pulls the maker half from the board). It loses a point only because the opening sentence is a conceptual explanation rather than a crisp verb-first statement of the tool's action.

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?

Three invocation shapes are spelled out: both halves directly, `halfId` alone for an offer this server already took, or `offerId` plus `takerHalf`/taken `halfId` for a board offer. Retry guidance is explicit ('run it again with the same arguments'). What is missing is a comparison against the other sponsor tools in the sibling set (sponsor_finalized_transaction, sponsor_unbound_transaction, build_sponsorable_transaction) — the agent gets no rule for choosing between them.

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?

No annotations exist, so the description carries the full burden and does: it discloses the ~1 minute blocking wait, the return shape { status, txHash, transactionHash, result }, the per-wallet dust lock and resulting concurrency ceiling (N = registered dust backings), the account-style conflict failure mode with errorCode CHAIN_EXECUTION_FAILED and its hash, and idempotent retry behavior. That is exactly the sort of mutation/concurrency/side-effect context annotations would otherwise supply.

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?

Purpose and channel selection are front-loaded in the first sentence, and the dense parentheticals (version tag, lock semantics, error code) all convey operational facts rather than filler. It is long and somewhat cramped for one paragraph, but nearly every clause earns its place given the concurrency and retry caveats it must carry.

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 no-annotation, no-output-schema mutation tool, everything an agent needs is present: how to build the input, what the tool returns (compensating for the missing output schema), how long it blocks, how conflicts manifest, and the recovery path. Nothing material is left to inference.

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 four parameters (file, txId, unboundTxB64, idempotencyKey) are already documented, including the txId provenance from build_sponsorable_transaction; the description adds no per-parameter format or constraint detail. It does reinforce the retry contract ('run it again with the same arguments'), which is marginal value over the schema's idempotencyKey wording, so the baseline 3 is right.

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 (submit), a specific resource (unbound proven+signed caller transaction) and the exact scope (cross-server fee sponsoring, parallel channel, NIGHTGATE 0.18.0). It explicitly positions itself against sponsor_finalized_transaction as the alternative channel, so an agent can tell the two sponsors apart without reading either 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?

Gives explicit when/when-not: use the parallel channel for buildSponsorable({bind:false}) transactions, 'do not mix both channels on one sponsor wallet', and rebuild-rather-than-resubmit after a CHAIN_EXECUTION_FAILED conflict. It also tells the agent what to do on a cut-off or pending call (rerun with the same arguments picks up the existing job).

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 discloses the entire execution model: build, prove, sign, sponsor payment, waiting for landing, witness privacy, return fields, free on-chain verification via check, failure guidance in next, and idempotent retry behavior. This gives an agent unusually complete behavioral context for a complex 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 front-loaded with the primary purpose and remains information-dense throughout. It is somewhat long and enumerates call types that also appear in the enum, but nearly every sentence contributes operational or behavioral context for a complex 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?

For a complex seven-parameter mutation tool with no annotations and no output schema, the description is largely complete: it explains the pipeline, sponsorship, witness handling, return shape, verification, failure handling, and retry semantics. The main remaining gap is that alternatives such as build_sponsorable_transaction or sponsor_finalized_transaction are referenced but not fully positioned with when-to-use guidance.

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 seven parameters, including call enum, params, witnesses, idempotencyKey, contractAddress, and compiledArtifactRef. The description adds useful cross-reference context such as params being listed per call in build_sponsorable_transaction and the witness source, but it does not add much per-parameter meaning beyond the schema baseline.

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

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

The description states a specific verb and resource: run any AttestationVault call end-to-end, including build, prove, sign, sponsor, and wait. It explicitly distinguishes this pipeline from build_sponsorable_transaction, which only builds the call, and names the exact family of calls supported.

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: use this to execute a vault call in one go with caller seed and sponsor payment, and retry with the same arguments if interrupted or pending. It references build_sponsorable_transaction for the call/param list, but does not explicitly state when to choose that sibling instead, so the guidance is strong but not fully exclusionary.

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 whole burden and does well: it discloses that the sponsor pays the fee, that terms are validated against `expect` and refused before proving, that the offerId board entry is re-read and can refuse, that a refusing sponsor leaves the proven half held under `halfId`, and the returned fields ({ status, txHash, transactionHash, result.swap, id, terms }). It stops short of stating auth/wallet requirements or whether a settled swap is reversible, which is why it is not 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?

Dense and largely front-loaded, with the alternative paths and failure modes ordered sensibly. The opening protocol explanation (one half each, mirrored merge, sponsor pays) is background rather than this tool's action and delays the operative sentence slightly.

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 6-parameter, no-output-schema, no-annotation mutation tool it covers what the agent needs: the return shape is spelled out inline, both success and refusal paths are described, and the recovery tool is named. Missing only wallet/auth expectations and idempotency behavior, which the schema names but does not explain.

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 still adds behavior the schema cannot: `expect` is mandatory in practice because 'an offer is text from someone else', `submit` changes the response shape entirely, and `offerId` triggers a pre-proof board re-read. That is meaningful meaning beyond the field descriptions.

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

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

It names a specific verb and resource ('takes an offer', 'builds and proves the mirror half from this server's wallet') and situates it against siblings: post_swap_offer/build_swap_offer produce offers, sponsor_swap consumes the produced halves. An agent can tell exactly which half of the swap lifecycle this tool performs 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?

Explicit when-to-use branches: with submit:true the halves go straight to the sponsor, without it the answer carries both halves 'for sponsor_swap'. It also gives preconditions (ALWAYS pass expect), the offerId board-check path, the held-half recovery path via sponsor_swap({ halfId, offerId? }) or revert_swap_offer, and the race case where revert_swap_offer is required.

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?

No annotations are provided, so the description carries the full burden and does: it discloses that a miss returns verified:false rather than an error, that it reads live on-chain state through a public service at no cost, and exactly which fields the result carries. It also preempts a likely misreading by explaining that bindingRegistered=false is normal for records anchored without a document id.

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 action and the record-identity model are front-loaded, and every following sentence supplies decision-relevant detail: lookup modes, optional cross-checks, the not-an-error result, and the bindingRegistered caveat. Dense but 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?

With eight optional parameters, no annotations and no output schema, the description still covers the missing pieces: the return contract (verified, attesterId, payloadHash, recordKey, documentId, schemaOk, bindingRegistered) and the failure semantics. Nothing an agent needs in order to call and interpret this tool is absent.

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 goes further by stating cross-parameter rules the schema cannot express (attesterId required unless documentId is given; payloadHash must match the bound record when documentId is used) and by explaining what documentId lookup reveals. It does not elaborate on network or compiledArtifactRef beyond schema text.

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 attester's record of a payload hash in an AttestationVault against LIVE contract state, with the zero-crawl/no-txHash clarification. It also defines the record identity model (one attester, one payload, recordKey(attesterId, payloadHash)), which makes the tool concrete. It does not name or differentiate from the sibling verify_predicate, which keeps it off 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?

Gives clear conditions: use name-based lookup by attesterId + payloadHash, or via a bound documentId, and optionally pin contentRoot/schemaId. The 'crawler-free, no txHash needed' and 'free, reads the public verify service' notes tell the agent when this is cheaper than transaction-based verification. No explicit exclusion relative to verify_predicate or the anchor/submit 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?

With no annotations, the description carries the full burden and does well: it discloses that verification reads live on-chain state, is free/public, is id-free, that a threshold scaling mismatch yields verified:false, and that claims are bound to a single attester's record. It does not fully describe return shape beyond the failure case or explicitly state auth requirements.

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 purpose is front-loaded, and every sentence carries operational information: predicate-specific requirements, scaling pitfalls, recomputation workflow, attester binding, and cost. Dense but not bloated.

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

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

For a complex 14-parameter tool with no annotations and no output schema, the description covers the main workflow and pitfalls. It could say more about return values and the documentIntegrity/documentDiff/cross-root predicate kinds, but the schema descriptions already document those parameters.

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%, but the description adds important semantic constraints: threshold must be the same scaled integer the circuit hashed, setRoot must be recomputed via prepare_membership_set, fieldKey is needed for field-bound proofs, and attesterId is part of the claim coordinates. This is meaningful guidance beyond the schema text.

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 a ZK claim against LIVE Midnight contract state. The 'Id-free: works for proofs NIGHTGATE never saw' clause gives it a distinct identity, though no sibling tool is explicitly named or contrasted.

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 this is useful (id-free verification of proofs not seen by NIGHTGATE) and gives per-predicate requirements, but it never explicitly says when to choose this over verify_attestation or prepare_document_proof. Usage is implied rather than spelled out as a routing rule.

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