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

Annotations already cover the read-only, idempotent, non-destructive profile, so the bar is lower; the description still adds real behavior the annotations can't express — the live-gas-price exit check, the cooldown read, and crucially the pricing model (free by default, 0.003 USDC only when the operator sets MCP_PAYWALL=true). It does not describe response shape, but that is covered by the output schema.

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

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

Front-loaded with the core capability, then the conditional parameter behavior, then the payment caveat — a sensible ordering. It is dense but each clause carries information; the payment sentence is the only part that could arguably be trimmed, though the cost disclosure is worth keeping.

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 a 3-parameter schema, full schema descriptions and an output schema, the description covers everything an agent needs to call it correctly: inputs, computed outputs, conditionality on daily_burn_usd, and cost. The only missing element — sibling differentiation — is scored under purpose/usage rather than completeness.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description genuinely adds meaning beyond the schema: it explains that daily_burn_usd triggers runway-in-days computation and a specific allocation split (seven days of spend kept in USDC, only surplus considered for GBLIN). That is decision-relevant semantics the schema does not contain.

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 ('Analyzes') and resource ('an agent wallet's treasury') and enumerates the computed outputs: GBLIN/USDC/ETH balances, whether ETH covers an exit at live gas price, and the redemption cooldown. It is clear what the tool does, but it never distinguishes itself from the nearby get_treasury_state or plan_treasury siblings, leaving the agent to infer which treasury view to 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?

The description gives a conditional usage signal ('When daily_burn_usd is given it adds days of USDC runway...'), which tells the agent what changes with the optional parameter. However, it offers no when-to-use/when-not guidance relative to get_treasury_state or plan_treasury, so the choice among the three treasury tools is left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds substantial context beyond that: the Dutch-auction mechanics, the premium ramp from discount to cap, the fact that the vault pays nothing, and that returns include unsigned approval+bid calldata. It omits auth requirements and rate limits, but the domain behavior is well disclosed.

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 is front-loaded in the first clause, and the prose is dense with domain information rather than filler. It runs long and the closing line ('nothing is paid out of the vault') partially restates earlier context, but every sentence conveys information useful for interpreting the auction state.

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 an output schema present the description needn't enumerate return fields, yet it usefully frames what each row means. Combined with zero parameters and full annotation coverage, the definition is nearly complete; the only shortfall is the absence of explicit invocation guidance relative to sibling tools.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-arg tool is 4.

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 gives a specific verb and resource — 'Read the GBLIN rebalancing auction on Base' — and the following sentences define exactly what the tool surfaces (per-row side, ETH gap, token/amount, unsigned calldata). An agent can distinguish this from siblings like get_treasury_state or get_governance_state without inspecting the schema.

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

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

The description explains the auction's existence condition ('when a basket row drifts past its band'), which implies the tool is worth calling to find rebalancing opportunities, but it never explicitly states when to call it, when not to, or how it relates to alternatives like quote_safe_swap or prepare_action. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description adds useful behavioral detail — the exact governance facets read and that passing operation_id changes the response to include that operation's status. It does not mention permission requirements or freshness/caching, hence 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?

Two dense sentences with the core governance read first and the optional operation_id behavior second; nothing is redundant except the trailing 'Read-only', which is minimal.

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

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

An output schema exists, so return-value explanation is unnecessary; for a zero-required-param, single-optional-param read tool the description covers scope, the optional path, and safety fully.

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 defines the 0x 32-byte hex format, so baseline would be 3; the description earns a bump by explaining the semantic effect of supplying operation_id (status of that specific timelock operation), which the schema only calls 'inspect'.

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

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

Specific verb ('Reads') plus a named resource ('GBLIN protocol governance') followed by an enumeration of what is returned: vault ownership by the timelock, min delay, grace period, role member counts, pending proposals. This clearly separates it from siblings like get_treasury_state or get_auction_state.

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 implies usage by describing the content (governance/timelock inspection) and notes the optional operation_id path, but never states when to prefer this over get_treasury_state or the other state tools, and gives no exclusions or prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds real beyond-schema context by naming the data provenance (Crash Shield vs Chainlink oracle peaks on Base) and the exact cost model (free unless MCP_PAYWALL=true, then 0.002 USDC). It omits freshness/caching behavior for a 'current' reading, 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?

Three sentences, front-loaded with the returned values and enums, then provenance, then payment terms — no filler. The paywall sentence is long and slightly dense, but every clause carries operative 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?

With an output schema present and annotations covering the safety profile, the description only needs to add cost, provenance and access preconditions — and it does all three. An agent can decide to call it and handle the paywall branch without further information.

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 _payment is fully documented there, so the baseline is 3; the description earns a bump by explaining the payment condition that motivates the _payment proof parameter. It still doesn't restate the omit-on-first-call 402 handshake, but the schema handles that.

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

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

Specific verb+resource with enumerated outputs ('risk regime (calm | elevated | crash)', severity score, posture), which lets an agent predict the return shape precisely. It does not explicitly contrast with the nearest sibling (verify_risk_attestation), so it stops short of a 5.

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

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

The description clarifies a prerequisite-style condition ('Independent of holding GBLIN') but never states when to call this versus alternatives such as verify_risk_attestation or how the regime should gate other flows. Usage is implied by the resource name rather than stated.

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

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

Annotations already establish readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real behavioral context beyond that: values are read from the chain at past blocks rather than live, and the series is bounded by the vault's deployment date. It does not discuss sampling cost or how reorgs/past-block reads are handled, but the essential traits are disclosed.

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

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

Two sentences, front-loaded with what the tool returns and followed by the data-window constraint and comparison use case. Slightly dense in the opening clause, but no sentence 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?

With an output schema present, the description need not enumerate return fields, and it correctly focuses on data provenance and window semantics. Combined with full parameter documentation and annotations, an agent has enough to call this correctly; only the ambiguity against analytical siblings remains.

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% – both 'points' (2-90, default 30) and 'interval' (hour/day, default day) are documented in the schema, including defaults and the 'newest last' ordering. The description adds nothing about the parameters, so the baseline 3 applies.

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

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

The description names the specific resource and metric (NAV per GBLIN share over time) plus the bundled series (ETH/USD and BTC/USD oracle prices, window change, max drawdown). It is unambiguous about what comes back. It does not explicitly contrast with any sibling, though no sibling covers NAV history, so the risk of confusion is low.

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

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

Usage is only implied: 'can be compared with holding ETH or BTC over the same span' suggests an analyst comparing vault performance against benchmarks. There is no explicit when-to-use, when-not-to-use, or named alternative among siblings such as get_treasury_state or analyze_treasury_health, which an agent would have to disambiguate on its own.

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

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

Annotations already cover safety traits (readOnlyHint, idempotentHint, destructiveHint, openWorldHint). The description adds meaningful behavioral context beyond annotations: the log is public and free forever, the returned receipt is portable and includes canonical payload, Ed25519 signature, RFC 6962 Merkle inclusion proof, and C2SP checkpoint, and it can be verified offline with verify-receipt.mjs. It does not mention rate limits or error behavior for out-of-range indices, but it adds substantial value over the structured annotations.

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 scope in the first sentence, followed by return details in the second. It is appropriately sized for a technically rich tool, though phrases like 'free forever' and 'zero dependencies' are mildly promotional and not strictly necessary for invocation correctness.

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 an output schema present and rich annotations, the description is complete for an agent to call the tool correctly. It supplements the structured fields with verification context and return composition, and no critical invocation information is missing.

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

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

Schema description coverage is 100%, and the single index parameter is fully documented in the schema, including zero-based semantics and a link to the log overview. The description only repeats 'by index' without adding new syntax or format details. Baseline 3 is appropriate when the schema already does the heavy lifting.

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: fetch a sealed AI Action Receipt by index from GBLIN's public transparency log. It is clearly distinguishable from sibling tools like seal_action_demo or verify_risk_attestation, which perform different operations on related concepts. An agent can identify exactly what this tool does without opening the schema.

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

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

The purpose implies the use case: retrieve a receipt when you have its index and want the full verifiable artifact. However, the description does not explicitly state when to use this tool versus alternatives such as verify_risk_attestation or get_transaction_status, nor does it provide exclusions or prerequisites. Usage is therefore implied but not fully guided.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety behavior is covered. The description adds meaningful behavioral context beyond annotations: pending/succeeded/reverted/not found outcomes, block and confirmation reporting, fee paid, token movements, and decoded revert reasons. It does not discuss operational limits such as caching or rate limits, but it substantially improves transparency.

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 immediately states what the tool reports, followed by a tightly packed list of relevant outcomes. Every clause maps to useful behavior or return information, 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?

Given the output schema, annotations, and fully documented input parameter, the description is complete enough for an agent to understand the tool's purpose and call it correctly. It covers status categories, failure reasons, and token movement reporting, leaving no critical gap for this read-only lookup 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?

There is one required parameter with 100% schema description coverage, and the schema documents the hash format and pattern. The description says the tool reports on a transaction but does not add hash-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource: it reports what a sent Base transaction did. It also enumerates the outcomes and returned data, making the tool's purpose clear. It does not explicitly distinguish itself from the sibling get_receipt tool, so it falls short of a 5.

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

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

The phrase 'sent Base transaction' implies a post-send status check, and the listed statuses clarify the expected context. However, there is no explicit guidance on when to use this tool versus alternatives such as get_receipt, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds one genuinely useful detail beyond that: 'whether the NAV is reliable', signaling that the returned NAV can be stale or untrustworthy. It stops short of saying why the NAV might be unreliable or whether the read is live on-chain vs cached.

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

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

A single front-loaded sentence with the verb and scope first, followed by the concrete data points returned. No filler, no restatement of the tool name, every clause carries 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?

An output schema exists, so return shape need not be re-explained, and annotations carry the safety profile; the description's enumeration of state components is sufficient to decide to call it. Minor gap: freshness/latency and what makes the NAV unreliable flag flip are not addressed, which matters for a live-state read.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing input discussion.

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 ('current GBLIN protocol state on Base mainnet') and enumerates the returned fields: NAV in USD, basket composition with dynamic weights, Crash Shield status, NAV reliability. However, it never distinguishes itself from close siblings like analyze_treasury_health and get_nav_history, leaving the agent to infer the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. With overlapping siblings (analyze_treasury_health, get_nav_history, get_auction_state) present, the description gives the agent nothing to route on beyond the tool's own subject matter.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-derivable context: this is documentation, not an action, and the paid path costs 0.0045 USDC per seal via x402 on Base with offline verification available. It stops short of saying whether the returned reference is static or whether calling it has any side effects/costs.

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

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

Two sentences, front-loaded with the return value and its contents, followed by the tier contrast. The parenthetical pricing detail earns its place. Slight density in the first sentence (a five-item list plus chain and protocol) but no filler.

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

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

An output schema exists, so return values need no prose explanation, and with zero parameters there is no input burden. For a read-only reference endpoint, stating what the reference covers plus pricing and the free-tier boundary is sufficient 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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly does not waste words on nonexistent inputs.

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

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

States a specific verb+resource ('Returns the reference for unlimited paid seals') and then enumerates exactly what that reference contains: endpoint, body schema, payment flow, offline verification. The pricing line (0.0045 USDC via x402 on Base) and the free-demo contrast make it distinguishable from seal_action_demo without opening any schema.

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

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

The closing sentence about the free demo (5 seals/day per IP) gives the agent the implicit trigger for using this tool: when the free tier is insufficient. However, it never explicitly states the alternative ('use seal_action_demo for free trials') nor does it point at the payment siblings (prepare_gblin_payment, relay_gblin_payment, verify_gblin_authorization) that the described payment flow must involve.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description is fully consistent, saying the tool returns calldata rather than executing. Beyond the annotations it adds real value: the Uniswap V3 swap-to-WETH route, the non-zero minimum output safeguard, and the warning that mint and management fees are governance parameters read live rather than fixed. It stops short of covering failure modes or approval-amount semantics.

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

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

The core function is front-loaded in the first sentence, followed by the two-step mechanics and fee caveat. Four sentences with minimal waste, though the parenthetical basket definition and the fee disclaimer could be tightened 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?

An output schema exists, so return values need not be explained. Given that, the description covers everything an agent needs: what is produced, the two-step execution path, the swap venue, slippage protection, and the fact that fees are dynamic governance parameters. Nothing material is missing for a two-parameter read-only calldata builder.

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 both parameters are already documented and the baseline of 3 applies. The description adds only marginal context — that the USDC is swapped and the wallet is the signer — but does not clarify decimal precision, whether the amount is in base units, or approval-amount relationships.

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 a specific verb and resource — returns calldata converting USDC to GBLIN — and defines what GBLIN is (a basket of cbBTC, WETH, USDC). It clearly separates this from a plain swap by describing the NAV mint mechanism. It does not, however, distinguish itself from the reverse-direction sibling swap_gblin_to_usdc_jit, leaving that inference to the agent.

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

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

The description gives a useful procedural breakdown (approve USDC, then call buyGBLINWithToken), which tells the agent how the returned calldata is meant to be used. But there is no explicit statement of when to prefer this over quote_safe_swap, preview_steps, or prepare_gblin_payment, and no exclusions or prerequisites. Usage is implied rather than directed.

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?

Goes well past the annotations: it gives the operating-cash formula, names the simulation components (vault-live fees, estimated exit value, round-trip cost), and lists concrete blockers (Crash Shield, redemption cooldown, ETH for the exit). Annotations only say readOnly/idempotent; the description adds the mechanics an agent needs, plus a risk disclaimer that GBLIN is crypto exposure, not cash or yield.

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 verb and result, and every clause carries information - formula, simulation contents, blockers, read-only status, risk caveat. However it is one dense, run-on sentence of roughly 80 words; splitting it into two or three would aid scanning without losing content.

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 read-only, open-world planning tool with an output schema and full annotation coverage, this is complete: it says what is computed, what the plan contains, what can block it, and that nothing executes or is advised. Return-value shape is covered by the output schema, so no further detail is owed.

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 the derivation the schema cannot express: operating cash = max(reserve_usd, daily_burn_usd x days), which explains how the two optional params interact and which wins. It also restates the trial-amount default. Incremental value over the schema is real, though modest.

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 ('turns idle USDC into a reviewable plan in one call') and enumerates the plan's contents, so the agent knows exactly what it gets back. The closing contrast with execution tools ('nothing is executed') separates it from invest_usdc_to_gblin and swap_gblin_to_usdc_jit without needing to open their schemas.

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

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

Usage is implied rather than stated: 'reviewable plan' plus 'read-only, nothing executed' signals this is the pre-flight step before an execution sibling, but no sibling is named as the alternative. There is also no explicit statement of when not to use it (e.g. for wallets with no USDC, or when only a quote is wanted).

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

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

Annotations already declare readOnly, idempotent and non-destructive; the description reinforces and extends this by confirming nothing is signed or sent. It adds real behavioral context beyond annotations: transaction ordering, gas limits embedded in each step, non-zero output bounds, and the Zap routing details.

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, then per-action semantics, then the safety guarantee. Dense but nearly every clause carries information; the parenthetical chains are slightly heavy 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?

An output schema exists, so return values need not be described, and the description still says steps are returned. For a multi-action builder of unsigned transactions this is close to complete; only prerequisite context (e.g., token approvals before minting) 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 baseline is 3; however the description genuinely adds value by defining the unit of `amount` per action (ETH, WETH, USDC, shares, or the USDC needed) and confirming `row` is bid-only with a largest-gap default, which goes beyond the schema's generic 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?

States a specific verb and resource ('Builds the unsigned transactions for an operation on the GBLIN vault') and enumerates all seven actions with their units. It does not explicitly name a sibling, but the enumeration and the 'unsigned, nothing signed or sent' framing make the scope unmistakable.

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

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

Usage is only implied: 'the steps are returned to the caller' hints that this is a preparation step to be followed by signing, and per-action notes ('exit_to_eth ... all or nothing', 'amount = the USDC needed') narrow inputs. No explicit when-to-use/when-not or comparison to alternatives such as preview_steps, seal_action_demo, or quote_safe_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?

Annotations declare readOnlyHint=true and the description is consistent: the tool only builds and returns messages, never submits or holds keys ('No private key is requested, held or transmitted'). It adds substantive context beyond annotations — EIP-3009/EIP-712 mechanics, domain read from the token rather than assumed, and relay forcing method 'transfer' — but does not discuss validity/expiry consequences or failure modes.

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 what it produces and why it matters, and each sentence carries new information (gaslessness, method choice, relay mode, key safety). It is dense and slightly long, but no sentence 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?

For a multi-artifact preparation tool with an output schema and full annotation coverage, the description covers inputs, modes, signing flow, and the no-key custody guarantee. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so all seven parameters are already documented in the schema. The description reinforces method/relay semantics and the front-running rationale, but adds little that the schema does not already state (live NAV conversion, default 600s, forced 'transfer'), so the baseline 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+resource ('Builds a gasless GBLIN payment') and immediately enumerates the three artifacts returned (EIP-712 message, calldata, x402 payload). It clarifies its role versus a submitting tool through the relay/method discussion, though it never names the actual siblings relay_gblin_payment or verify_gblin_authorization.

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 selection criteria among its own modes: 'receive' when only the recipient should submit (front-running protection), 'transfer' for an x402 facilitator, and 'relay: true' when nobody else will carry it on chain. It lacks routing guidance against the sibling submit/verify tools, so 4 rather than 5.

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

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

Annotations already flag readOnly/idempotent/openWorld, and the description goes well beyond them: it explains the sequential state model, the exact per-step outputs (success, gas used, gas-limit sufficiency, decoded revert reason) plus net token/ETH movement, and warns that chain state can change so a preview is not a guarantee.

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

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

Three sentences, front-loaded with the core simulation behavior and followed by input spelling and output shape. Dense but nearly every clause carries information; the parenthetical approval-before-mint example slightly pads an already-clear 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?

Even though an output schema exists, the description still summarizes return shape and explicitly flags the non-determinism caveat, which structured fields cannot convey. For a read-only simulation tool with 2 fully documented parameters, nothing needed to invoke or interpret it 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 the baseline is 3; the description nonetheless adds the alias contract (target or to, calldata or data), the optionality of value and gas, and that value is denominated in wei. It does not mention the 8-step maximum enforced 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 and resource — simulate a sequence of transactions against the latest Base block — plus sequencing semantics ('each step sees the state the previous ones left'). This clearly separates it from sibling write/prepare tools like prepare_action and get_transaction_status.

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

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

'before anything is signed' establishes the pre-signing context and the caveat that a successful preview is evidence, not a guarantee. It does not explicitly name which sibling to use instead (e.g. prepare_action for construction, get_transaction_status for post-send), so alternatives are left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the dynamic slippage buffer (2.5% normal / 4% during Crash Shield) and the fee breakdown returned.

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

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

Two tightly written sentences, front-loaded with the core purpose and return values. Every sentence adds 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?

An output schema exists, so return values need not be explained in full, yet the description still summarizes them. Annotations cover safety, and the description adds the slippage and fee context, leaving no critical gaps for correct invocation.

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

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

Schema coverage is 50%: amount_in has a description, but direction has only an enum. The description compensates by mapping buy to ETH→GBLIN and sell to GBLIN→ETH, clarifying the missing half of the parameter 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?

States a specific verb (preview) and resource (buy/sell ETH↔GBLIN), and explicitly distinguishes from execution with 'without executing'. An agent can tell this is a read-only quote tool separate from swap execution 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?

The phrase 'without executing' implies the tool is for previewing before a swap, but it does not name any alternative tool or state when not to use it. No explicit routing to siblings like swap_gblin_to_usdc_jit or preview_steps is provided.

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?

Adds real behavior beyond annotations: on-chain verification and simulation before submission, Multicall3 atomicity ('either both settle or neither does'), fee conversion at live NAV, and the explicit 'this tool moves funds' warning. It does not cover failure/revert handling or rate limits, but the destructive/idempotent/openWorld profile is already carried by annotations.

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 purpose, then mechanics, then the fund-movement warning. Nearly every sentence earns its place; the 'Returns the transaction hash and its outcome' line is partly redundant given the output schema, and the Multicall3 name is detail most agents don't need.

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 fund-moving tool with nested objects, the description supplies atomicity, fee pricing, and prerequisite signatures, while annotations cover the safety profile and the output schema covers returns. What's missing is what happens on failed simulation/verification and whether re-submitting the same signed authorization is safe despite idempotentHint.

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?

With 100% schema coverage the baseline is 3, but the description adds meaning the schema does not: both structures are signed by the payer's wallet, and the fee is denominated in GBLIN priced at the live NAV. The distinction between payment and fee semantics comes through even though the nested 'authorization' object itself stays opaque.

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 ('carries a signed GBLIN payment on chain') plus the distinguishing scope condition ('for a payer that holds no ETH'). An agent can separate this from prepare_gblin_payment or verify_gblin_authorization without opening the schema, since this is the tool that actually submits.

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 context is implied rather than stated: the payer must hold no ETH and the authorizations must already be signed, with the fee 'prepared with relay: true' noted only in the schema. No explicit when-not condition or named alternative (e.g., prepare_gblin_payment as the prerequisite step) is given.

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

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

Goes well beyond annotations, which only declare non-read-only, open-world, non-idempotent. The description adds the rate limit (5/day/IP), that receipts are marked demo:true, that the action label and metadata become public and permanent, and precisely what the receipt contains (Ed25519 signature, Merkle inclusion proof, C2SP checkpoint, offline verification via verify-receipt.mjs). That is exactly the context a caller needs before publishing.

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

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

Front-loads the operation and its target log, then layers limits, return value, and the paid alternative in a compact block. Dense but every clause (demo quota, demo:true marking, public visibility, receipt components) carries decision-relevant 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?

No output schema exists, yet the description fully describes the return value and its offline verification path. For a write tool that publishes to a public log, it covers quota, permanence, receipt shape, and the paid escalation path — nothing an agent needs to call it safely 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 the schema already carries the parameter definitions. The description still adds meaningful semantics beyond it: only sha256 hashes go in, content must be hashed locally, while action label and metadata are published. That reinforces the privacy contract of each parameter rather than restating it.

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 ('Seals') and resource ('hashes of an AI action into GBLIN's public append-only RFC 6962 transparency log'), scoping exactly what is written and where. An agent can distinguish this from prepare_action or how_to_seal_paid 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?

Clear context for when to call: free demo limited to 5 per day per IP, with a pointer that unlimited sealing lives at the separate paid x402 endpoint. It also warns that label and metadata are published publicly, which steers callers away from this tool for sensitive content. It does not explicitly compare against the sibling how_to_seal_paid or prepare_action, so not a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, so the description's value-add is the explicit disclaimer that the referral code is a label only, not embedded in any transaction, and no fee is paid. That preempts a plausible misuse assumption. It does not say whether the seed is freshly regenerated per call, which is why it isn't 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?

Three sentences, zero waste: what is generated is front-loaded, then contents, then the fee/label caveat. The negative clarification earns its place by preventing a misunderstanding.

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

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

An output schema exists so return shape needn't be explained, and the generation plus referral-code semantics are covered. Minor gap: nothing says whether the seed targets a specific peer or is generic beyond peer_context customization, though the schema largely carries that.

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 peer_context, caller_wallet (hashed into the referral code), and example_amount_usdc with default and range. The description reinforces caller_wallet's role but adds no new syntax or format detail beyond structured fields, so the baseline 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 and artifact: 'Generates a portable skill seed' for installing the GBLIN MCP server. This is unmistakably different from every sibling tool (swaps, treasury, payments, receipts), so an agent can route to 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?

The name and description imply the use case (onboarding a peer agent), but there is no explicit statement of when to call this versus alternatives, nor any exclusion. Usage is inferred rather than directed.

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?

Extremely rich disclosure beyond annotations: the three sequential transactions, all-or-nothing redemption, non-zero minimum per step, ETH above minimum stays in the wallet, EOA vs ERC-4337/EIP-7702 signing behavior, and that it is free of protocol fee with costs limited to Zap swaps and gas. Returning calldata is consistent with readOnlyHint=true, so no contradiction.

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 is front-loaded, then the mechanism, batching, minimums and cost are layered efficiently. It is dense for a single paragraph but nearly every clause carries decision-relevant information; minor trimming of the mechanism detail could tighten it further.

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

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

For a three-transaction calldata builder with an output schema covering return values, the description supplies everything needed to call correctly: what it produces, the step sequence, batching behavior, slippage/minimum guarantees, and cost profile.

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 both parameters are self-documented, so the schema carries the load. The description adds the sub-meaning that usdc_needed is the exact amount that will be guaranteed out and wallet_address drives a cooldown check, but does not add format detail beyond the schema. Baseline 3.

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: returns ready-to-broadcast calldata that redeems exactly the requested USDC from a GBLIN position. The JIT-for-x402 framing plus the explicit three-step mechanism makes the operation unambiguous and distinguishable from generic payment-prep tools.

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

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

Gives concrete context: use when you need USDC to cover an x402 invoice or any USDC obligation against a GBLIN position. It stops short of naming an explicit alternative (e.g., prepare_gblin_payment) or a when-not condition, so a 4 rather than 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?

Goes well past the annotations, which only declare read-only, idempotent, non-destructive, open-world. It enumerates the exact checks (EIP-712 signer recovery, ERC-1271 for contract payers, validity window vs on-chain time, nonce used/cancelled, payer balance) and the two possible outcomes: ready calldata or failing reason. That tells the agent its network-dependency and failure behavior concretely.

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

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

Front-loads the purpose and then the checks, with the outcome stated last; every sentence carries information. It is somewhat dense for three sentences, but nothing is redundant with the annotations or the schema.

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?

Complete for a complex, nested-input verification tool. With an output schema present, the description need not detail return values, yet it still signals a verdict plus calldata or a failing reason, and it covers the cross-cutting concerns (contract payers, on-chain time, nonce state) that make the tool's result interpretable.

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% and the schema documents all three parameters, including the method enum default, so the baseline of 3 applies. The description adds domain meaning (signature is verified by signer recovery, ERC-1271 fallback for contract payers) but does not explain the receive/transfer method distinction or the authorization object fields 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?

States a specific verb and resource (checks a signed GBLIN authorization) plus the decisive scope detail: before any gas is spent. This distinguishes it from the sibling prepare_gblin_payment and relay_gblin_payment as a read-only pre-flight check rather than an action that submits.

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 situational context ('before any gas is spent on it') and frames the verdict against what an x402 facilitator checks, so the agent knows when to reach for it. It stops short of naming explicit alternatives or exclusions, e.g., when to use prepare_gblin_payment or relay_gblin_payment instead.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses that the call is free, enumerates the four concrete checks performed (EIP-712 recomputation, signer recovery against GBLIN's published attestor, 10-minute freshness against on-chain time, live regime drift). It also clarifies conditional behavior — signature recovery only applies 'when a signature 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?

Front-loads the core action and cost in the first clause, then spends the remainder on a compact numbered list of checks. No filler sentences; every phrase either scopes the input or names a verification step.

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 verification tool with an output schema already present, the description supplies everything an agent needs: accepted input shapes, cost, what is being checked, and the time-validity window. Return-value formatting is correctly left to the output schema rather than duplicated.

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 semantic nuance: it clarifies that attestation_id, signature and attestor are consumed only when present, and it frames the expected_attestor parameter as a comparison target rather than a mere input. It stops short of explaining what a mismatch on expected_attestor produces, but the conditional-usage semantics are materially clearer than the schema alone.

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

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

Names a specific verb (verifies) and a specific resource (GBLIN Risk Attestation), and enumerates the three accepted input forms (the /api/x402/attestation object or a peer-attached proof-of-diligence). The resource is clearly distinct from the sibling verify_gblin_authorization, so an agent can select 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?

Implies usage by describing accepted inputs and stating 'Free', which tells the agent there is no cost barrier to calling it. However, it never says when to prefer this over verify_gblin_authorization, nor does it state when verification is unnecessary or what to do on failure — usage is inferred rather than prescribed.

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