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 sponsor fee payment, wait time, first-call prover-key download, on-chain data limits, seed ownership via attesterId, return fields, retry deduplication behavior, and that a separate same-argument call requires a new idempotencyKey.

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

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

The description is dense but front-loaded, starting with the core action and then covering return shape, timing, on-chain visibility, and retry semantics. Every sentence adds operational information needed to invoke or safely retry 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 complex, multi-step anchoring operation with no annotations and no output schema, the description is highly complete. It explains asynchronous timing, sponsor mechanics, return fields, verification linkage, and idempotency behavior, leaving little an agent needs to infer before calling 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 description coverage is 100%, so the schema already defines each parameter. The description adds useful cross-parameter meaning: schemaId and contentRoot come from prepare_document_proof, the content root is needed by submit_vault_call field claims, and idempotencyKey governs retry versus new-call semantics.

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

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

The description states a specific verb and resource: anchoring a document hash on Midnight in a single call. It also clarifies the end-to-end scope—building the attest transaction, sponsor-paid fee, waiting for landing—and names related tools such as prepare_document_proof and submit_vault_call, so the agent can distinguish it from siblings.

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

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

It provides clear usage context: call this to anchor a document hash, optionally anchor a content root when schemaId and contentRoot came from prepare_document_proof, and retry with the same arguments if interrupted or pending. It does not explicitly state when not to use it, but the pipeline relationships with prepare_document_proof, submit_vault_call, and verify_attestation are clear.

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 disclosure load and does so: sponsor pays for the transaction, the call blocks until settlement (~1 minute), the response shape is given, failure delivers a `next` hint, and the dedup/resume behavior on retry is spelled out. It also warns that a deliberate second call needs a fresh idempotencyKey.

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

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

Front-loaded with the action and effect, then constraints, then return/retry semantics in priority order. Dense but nearly every sentence does work; the retry/idempotency portion is slightly verbose relative to the rest.

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

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

For a 5-parameter mutation with no annotations and no output schema, the description supplies timing, failure handling, retry behavior, and return shape. Only minor gaps remain, such as why both txHash and transactionHash appear or how long dedup state persists.

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 beyond it by explaining the composite token identity (name + issuer) and what omitting issuerKey implies ('the token is one this wallet minted'). It also explains the idempotencyKey's dual role (resume vs. genuinely new call). It stops short of anything on amount units beyond what the schema says.

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: 'Burn an amount of a factory token this wallet holds', plus an effect clause ('the coins leave circulation and the factory's supply ledger drops'). That effect statement clearly separates it from mint_token and send_token among the siblings.

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

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

It gives concrete preconditions (factory must be on the sponsor's contract list and have burn on its circuit list) and states the issuerKey default behavior. It never names a sibling alternative or an explicit when-not-to-use, which keeps it below 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?

No annotations exist, so the description carries the full burden and does so richly: the caller needs neither NIGHT nor DUST, the sponsor pays, sync waits up to 20s (5 min from genesis), one pay-in runs at a time, failed calls refund coins, and it returns {status, txHash, transactionHash, result}. It also discloses the allowUnshieldedOffers grant requirement and the deduplication behavior on retry.

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 opening sentence is well front-loaded, but the body is a dense run-on of stacked parentheticals covering coin tagging, sync timing, sponsor channels, witnesses, and refunds. Most content is relevant, yet it is hard to parse and would benefit from structure or trimming.

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 mutation with no annotations and no output schema, it covers the return shape, blocking/settle timing (~1 minute), failure handling, retry/dedup, and funding/grant prerequisites. An agent has enough to call it correctly and interpret the outcome.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it documents the tagged value formats ($bytes/$uint/$coin/$night), explains that payUnshielded is implied by a $night argument, and details idempotencyKey dedup semantics. This goes well beyond the schema's 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?

States a specific verb and resource ('call a circuit on any contract') with a clear precondition (the lineage package installed next to the server) and summarizes the full build/prove/sign/sponsor pipeline. This distinguishes it from siblings like build_sponsorable_transaction or submit_vault_call, which are partial steps rather than the end-to-end call.

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 operational context clearly: it routes the agent to get_swap_wallet for the funding wallet, states retry semantics ('run it again with the same arguments'), and clarifies when a new idempotencyKey is needed. It does not explicitly name a sibling alternative or say when-not to use it, 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 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 thoroughly: it states 'Spends nothing', explains that only shielded coins are synced, discloses the roughly 5-minute genesis sync delay, and specifies the { synced: false, syncingSeconds } retry state. It also describes pending-balance semantics, reserved coin TTLs, released maker halves, and how pendingHalves relate to offered or restored halves.

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 information is relevant, but it is delivered as one long, densely nested paragraph with many backticked field names and subordinate clauses. It is front-loaded with what the wallet is, but the lack of structure makes the many return-state details harder to scan 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?

There is no output schema and no annotations, so the description must explain the return shape, and it does extensively. It covers balances, spendable amounts, pending returns, pendingHalves, reserved coins, released halves, offer metadata, and the unsynced response state, which is enough for an agent to call and interpret this complex read 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 input parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description does not introduce any parameter ambiguity.

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: the shielded swap wallet, including address, public keys, balances, spendable amounts, pending returns, pending halves, and reserved coins. It is more than a tautology and an agent can infer it is a state-reading tool, but it does not explicitly contrast itself with siblings like get_swap_offer, list_swap_offers, or my_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 mostly implied: use this to inspect the shielded wallet state. The description gives a useful retry instruction for the first-sync case ('call again'), and mentions relationships to revert_swap_offer and post_swap_offer, but it does not state when to choose this tool over the sibling offer-listing 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 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 load and does it well: it discloses that the seed never leaves the process, that a sponsor pays, that the call blocks for roughly a minute, that reruns dedupe instead of resubmitting, and what a failed response offers (`next`). Missing cost/permission details keep it from 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 action, then prerequisites, then return shape, then retry semantics — a sensible ordering with no filler. Some phrasing is compressed to the point of opacity ("built, proven and signed here"), which costs a point.

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 six-parameter mutation with no annotations and no output schema, it covers prerequisites, defaulting rules, blocking duration, success payload shapes ({ tokenType, domain, issuerKey } and { status, txHash, transactionHash, result }), failure handling and idempotency. Semantics of domain/issuerKey and any fee expectations are the remaining gaps.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real meaning on top — the recipient defaults to this wallet via get_attester_identity, and a different recipient requires *both* of its keys, which explains the schema's conditional requirement on recipientEncryptionPublicKey. It also clarifies that name is only half the token type identity.

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?

Opens with a specific verb and resource ("Mint a shielded token ... on a token-factory deployment") and immediately frames the process's role ("This process is the issuer"). An agent can tell it apart from burn_token, send_token and derive_token_type 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 (factory must be on the sponsor's contract list, mint on its circuit list) and full retry guidance including when a *new* idempotencyKey is needed for a deliberate second call. It does not explicitly contrast against sibling tools, 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 to lean on, the description carries the full load and does: it discloses the poster-only auth requirement, the key side effect (coins stay reserved until revert_swap_offer or the 15-minute release), and the non-error behavior for already-closed offers where a lapsed offer returns expired rather than throwing. It even declares the return shape { offerId, status }.

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 in the first clause, then layered with auth, reservation, and return semantics. It is dense but every sentence carries a real behavioral fact; the "(NIGHTGATE 0.40.0)" version tag and the jargon-heavy "half" phrasing are the only slightly noisy elements.

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 single-parameter mutation tool with no output schema and no annotations, the description covers auth, state consequences, idempotent-style error handling for closed offers, follow-up tools, and the return object. An agent has everything needed to call it and interpret the 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?

The single offerId parameter has 100% schema coverage including uuid format and a strict pattern, so the schema does the heavy lifting and baseline 3 applies. The description only implies offerId is the board entry via "Take an offer off the board" and adds no format or sourcing detail beyond the schema.

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

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

States a specific verb and resource: taking a swap offer off the board, with the scoping note that only its poster may do so. It names the related siblings (revert_swap_offer, get_swap_wallet) and makes clear this tool removes the offer rather than releasing its escrowed funds, so an agent can distinguish it from revert_swap_offer 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?

"Only its poster may" sets an explicit authorization precondition, and naming revert_swap_offer plus the 15-minute get_swap_wallet release tells the agent the follow-up paths for reclaiming coins. It stops short of an explicit when-to-use/when-not statement, but the context for choosing retire over revert is clear.

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 mostly meets it: it discloses the intermediate state ('coins count as spent in this wallet'), the terminal state ('a half whose swap landed leaves the list; its coins are spent'), the hard limit on cancellation (cannot recall a held offer), and the restart-survival property of the offerId path. It does not mention permissions, failure modes, or what the call returns, which keeps 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?

The critical action and its constraint are front-loaded, and every sentence carries non-redundant information. It is dense and the first sentence is long with an interleaved parenthetical tool list, which costs some readability, but 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?

With no annotations, no output schema and an optional-parameter schema, the description covers state effects, prerequisites, restart behavior and the primary failure case, which is what an agent needs. The remaining omissions — return value shape and the required-one-of rule for id/offerId — are the only things left unclear.

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 50% (only offerId is documented in-schema), but the description more than compensates by explaining what each selector targets — 'By id for a half listed by get_swap_wallet, also one restored from an earlier process' and 'by offerId for a board offer this wallet posted, from the board's copy of the half'. The one gap is that neither the schema nor the description states whether the two are mutually exclusive or what happens if both or neither are supplied.

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?

Opens with a specific verb+resource: 'Release the coins of a swap half this wallet built', and immediately names the sibling tools that produce such a half (build_swap_offer, take_swap_offer, send_token). It also distinguishes itself from retire_swap_offer by explaining that retirement is a prerequisite for one of the two cases, so an agent can route correctly 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 explicit when-to-use (a half that will not be used), the two selection paths with the alternative named in each case (by id for get_swap_wallet halves; by offerId for board offers), the prerequisite for the board case (offer must be closed; retire_swap_offer first while open), and an explicit when-NOT-to-use with the recommended alternative ('does not recall an offer somebody already holds: ... spend its coins in another swap').

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 thoroughly: the transfer is built and proven locally from the wallet's coins, only fee-unpaid bytes reach the server, the recipient needs only an address. It also discloses the two blocking waits (~1 minute each), the returned shape { status, txHash, transactionHash, result }, that receipt can be null and re-fetched, and that failed results carry a `next` instruction.

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 purpose, which is good, but the middle is a run-on with duplicated waiting language ('waits for the block (about a minute more)' then 'waits until the job settled (about 1 minute)') and a redundant 'txHash, transactionHash' pair. Several sentences could be merged without losing information.

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

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

For a sponsored transfer with no annotations and no output schema, the description covers prerequisites, local proof construction, server interaction, latency, return shape, receipt-null handling, and idempotent retry. Minor gaps: what happens on insufficient coins, and the maxInputs reference that has no corresponding parameter.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to idempotencyKey beyond the schema's bare 'Dedupes retries': same-argument retries are absorbed into the existing job and a separate transfer requires a fresh key. It also explains that at most maxInputs coins are consumed, though maxInputs is oddly referenced without being a declared parameter.

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

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

States a specific verb and resource with concrete scope: send a shielded token amount from this wallet to another shielded address, fee paid by the sponsor. The example uses (payout, salary, invoice settlement) make the intent unambiguous. It does not name any sibling tool to contrast against (e.g. sponsor_finalized_transaction or build_sponsorable_transaction), so it stops short of full sibling differentiation.

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

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

Gives clear preconditions (sponsorTransfer in the grant, token type on the sponsor's list, NIGHTGATE 0.39.0) and explicit retry rules: reuse the same arguments after a cut-off/pending call to dedupe, and use a new idempotencyKey only for a genuinely separate transfer. What it lacks is any 'use X instead when...' routing against the many sibling 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 so: sponsor pays dust, on-chain identity is the builder's not the sponsor's, server enforces a contract/circuit allow-list, default 30-minute TTL, server-side wallet selection, and a roughly one-minute block wait whose receipt may be null. It even documents dedup behavior on interrupted or pending calls.

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 are front-loaded and every major topic earns its place, but the waiting behavior is restated twice ('waits for the block (about a minute more)' and 'waits until the job settled (about 1 minute)'), and the return-shape sentence sits mid-paragraph rather than being grouped.

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 contract itself — { status, txHash, transactionHash, result }, the null-receipt case, and the failed -> `next` field. Combined with the retry, TTL and allow-list notes, an agent has everything needed to invoke and recover.

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 reinforces the parameter precedence (txId from build_sponsorable_transaction before falling back to file/base64) and adds retry semantics for idempotencyKey ('a second, separate call with the same arguments needs a new idempotencyKey') beyond the schema's terse note.

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: 'submit a FINALIZED, fee-unpaid transaction that was built, proven and signed elsewhere', and immediately names the sibling paths it is not (build_sponsorable_transaction, sponsor_unbound_transaction). An agent can distinguish it from the parallel-channel tool 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 states the channel explicitly ('SERIAL channel, one tx per sponsor wallet at a time') and routes parallel use to sponsor_unbound_transaction with bind:false. It also gives retry rules ('run it again with the same arguments: it picks up the job it started'), the new-idempotencyKey condition, and the TTL promptness requirement.

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 does so: it discloses that the sponsor pays the fee and dust, that the endpoint is off by default (NIGHTGATE_SPONSOR_ALLOW_SWAPS), that an agent grant needs sponsorSwap in allowedActions, and the hard constraints (one token type each way, allow-list, never NIGHT, max 4 inputs / 2 outputs, mirrored halves). It also discloses the single-fill failure mode, the ~1 minute block wait, receipt null on timeout, and dedupe-on-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?

Almost every sentence carries substantive information, but the text is a single dense run-on with redundant restatement — the result shape is described twice ({ txHash, transactionHash, swap } and then { status, txHash, transactionHash, result }), and the wait behavior is stated in two consecutive, overlapping sentences. It is not front-loaded: mechanism precedes the one-line 'what this does'.

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, high-complexity async job with no output schema and no annotations, the description covers return shapes, failure/next, timeout+re-fetch, dedupe and configuration gating — enough to invoke correctly. The remaining gap is sibling positioning against the other sponsor/submit tools, which the agent must infer.

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 routing meaning on top: halfId alone vs halfId alongside both halves, offerId sourcing the maker half from the board, and idempotencyKey as dedupe for the SAME two halves only. It does not explain takerSecret's directed-offer flow beyond the schema's own wording.

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 makes clear this tool settles a shielded two-token swap by merging two mirrored halves and having a sponsor check, merge and submit them, and it names take_swap_offer as the sibling that keeps the halves. It is specific about the resource and mechanism, but the opening is a mechanism walkthrough rather than a front-loaded 'sponsors/submits a swap transaction', and it never contrasts itself with the other sponsor_* siblings.

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

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

It gives concrete argument-combination routing: pass both halves, or halfId alone for an offer this server took, or offerId to pull the maker half from the board next to takerHalf/the taken halfId, plus the rule that a second identical call needs a new idempotencyKey. What is missing is guidance on when to pick this over sponsor_finalized_transaction, sponsor_unbound_transaction or build_sponsorable_transaction, which are the plausible 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 burden and does so: it discloses the per-wallet lock scope, the one-minute wait-until-settled semantics, the exact return shape, and the failed-job path including the CHAIN_EXECUTION_FAILED errorCode and recovery procedure. The conflict/loser-lands-on-chain behavior for account-style contract state is exactly the kind of hidden trait annotations would never have conveyed.

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 identity are front-loaded in the first clause, and the trigger/conflict/retry information follows in a defensible order. It is dense and crammed with run-ons and version jargon (NIGHTGATE 0.18.0, "N = its registered dust backings"), which slightly hurts scannability, but no sentence is pure filler.

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

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

For a complex asynchronous mutation with no annotations and no output schema, the description supplies everything an agent needs: the return object fields, the settle-wait expectation, the two distinct failure modes (conflict vs. cutoff/pending) and their remedies. Nothing material about calling it correctly 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 the schema already explains file/txId/unboundTxB64 precedence and idempotencyKey dedup semantics, establishing a baseline of 3. The description reinforces idempotency behavior but adds no selection guidance between the three input routes beyond what the schema states.

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

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

States a precise verb+resource (submit an unbound proven+signed transaction for cross-server fee sponsoring) and pins down the exact build mode (buildSponsorable({ bind: false })). It explicitly names the sibling sponsor_finalized_transaction and explains the distinction (parallel vs. serialized channel), so an agent can pick between them 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?

Gives explicit when-to-use (transaction built with bind:false), an explicit when-not ("do not mix both channels on one sponsor wallet"), and names the alternative channel. It also covers operational edge cases: retry with identical args is deduplicated, a genuine second call needs a new idempotencyKey, and a conflicting call must be rebuilt rather than resubmitted.

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 thoroughly: it discloses caller seed usage, sponsor-paid execution, waiting until the transaction lands, witness privacy, returned fields, on-chain verification via `check`, failed-job guidance, and deduplication semantics. This is unusually complete for a signing/execution 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 core purpose is front-loaded and every sentence carries relevant operational detail. The paragraph is dense and long, but the density is justified by the tool's complexity and there is little obvious filler.

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

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

For a complex execution tool with no output schema, the description explains the return object fields, on-chain verification, retry behavior and witness handling. The main remaining dependency is that per-call `params` details live in build_sponsorable_transaction rather than being enumerated here, but the description explicitly routes the agent there.

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 meaning by grouping the call enum into ZK claims, cross-document claims, disclosure, passports and anchoring. It also clarifies that `params` follows build_sponsorable_transaction, that witness fields come from prepare_document_proof, and that idempotencyKey controls retry deduplication.

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 by building, proving and signing it here. It distinguishes this from build_sponsorable_transaction by emphasizing the one-go execution and from prepare_document_proof by clarifying that the witness is consumed here but never sent.

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

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

It gives clear context for execution, witness handling and retry behavior, including when to reuse the same arguments and when a new idempotencyKey is needed. It names build_sponsorable_transaction as the source of the same calls and params, but it does not explicitly state when an agent should choose that sibling instead of this execution-oriented tool.

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.