gblin-treasury-risk-regime

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantive behavior: unsigned-and-unbroadcast output, step ordering, non-zero output bounds, per-step gas limits through vault and Zap, redeem having no fee and no price feed, and exit_to_eth being all-or-nothing. This is exactly the domain context annotations cannot carry.

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 a dense but necessary per-action parenthetical covering all seven enum values, closing with the signing/return behavior. Efficient for the scope, though the single run-on block with embedded parentheticals is harder to scan than a short list would 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 4-param tool with a full output schema, the description covers action units, bid defaults, and the unsigned output contract, so an agent can call it correctly. The remaining gap is the sibling relationship to actions.preview/status and the surrounding sign-and-relay workflow, which is left implicit.

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% (baseline 3), but the schema explicitly defers to the description for the amount unit ('see the description'), and the description supplies per-action unit semantics (ETH/WETH/USDC/shares) plus 'amount = the USDC needed' and the row default for bid. It adds genuinely necessary meaning beyond the structured field definitions.

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 and resource ('Builds the unsigned transactions for an operation on the GBLIN vault') and then enumerates every supported action with its unit and routing (mint_with_usdc through the Zap, bid against the rebalancing auction, etc.). An agent can tell what this tool does and which operation each enum value represents 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?

Usage is implied rather than stated: 'Nothing is signed or sent: the steps are returned to the caller' hints that this is a build step preceding signing, but the description never names when to choose it over siblings such as actions.preview, actions.status, or payments.relay, and gives no prerequisites or exclusions.

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, openWorld), and the description adds real context beyond them: each step sees prior state, the preview is 'evidence, not a guarantee' because state can change before landing, and it reports per-step success, gas, gas-limit sufficiency, and decoded revert reasons. It omits the 8-step cap and any rate/latency behavior, so 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?

One dense, front-loaded paragraph with no filler; the state-chaining and caveat sentences are the most valuable. The enumeration of per-step return fields is somewhat redundant given an output schema exists, which keeps it from a 5.

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 simulation tool with annotations and an output schema, the description covers the crucial non-structured facts: sequential state visibility, alias spellings, and the non-guarantee caveat. The only notable omission is the maxItems: 8 limit on steps, which an agent should know before composing a batch.

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 from, steps, and the to/target and data/calldata aliases. The description restates the aliases and notes value and gas are optional but adds no format or semantic detail beyond the schema, which is the expected baseline when the schema 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 gives a precise verb and resource ('Simulates a list of transactions in sequence against the latest Base block') plus the key scoping qualifier 'before anything is signed', which separates it from actions.prepare. An agent can identify the operation and its pre-signing role 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?

It clearly states the context of use: run the sequence as if the wallet sent them, before signing, so dependent steps (approval before mint) can be validated. It does not name an explicit alternative such as actions.prepare or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so safety is covered. The description goes beyond that by disclosing the state machine (including 'not found' as a non-error outcome), the network (Base), and that reverted transactions come back with a decoded reason — real behavioral context an agent cannot get from annotations alone.

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

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

One dense sentence, but it is front-loaded with the status outcomes and then the return contents, so the agent can stop reading early. The parenthetical token list is slightly heavy but each 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?

For a single-parameter read tool with a full output schema and complete annotations, the description supplies enough: it clarifies network, outcome semantics and revert handling. The only real gap is guidance on when to reach for this versus the prepare/preview siblings.

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 a single parameter with 100% schema description coverage and a regex pattern, so the schema fully documents it. The description adds only the implicit notion that the hash identifies a Base transaction; that is baseline, not added value.

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 ('Reports') and a precise resource (the outcome of a sent Base transaction), and enumerates the terminal states (pending, succeeded, reverted, not found). The phrase 'a sent Base transaction' implicitly separates it from actions.prepare/actions.preview, but no sibling is named outright, 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 post-send framing ('what a sent Base transaction did') implies you call this after submitting a transaction, but there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as actions.prepare or actions.preview. Usage must be inferred.

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 only cover the safety profile (read-only, idempotent, non-destructive, open-world). The description adds substantial behavioral depth beyond that: the four enumerated checks, the conditional nature of signature recovery (only when a signature is present), the 10-minute freshness window against on-chain time, and the live-drift comparison. This is far more than the structured fields provide.

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 and the accepted input types, then a tight numbered list of the four checks. Every sentence earns its place; nothing is redundant with the name or annotations.

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

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

An output schema exists, so return-value explanation is unnecessary. Given the complexity of cryptographic verification, the description supplies exactly the behavioral context an agent needs (what is checked, the freshness window, conditional signature handling) and is complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents both parameters well. The description still adds value by clarifying the differing origins of the `attestation` input (GBLIN endpoint object vs. peer-attached proof-of-diligence) and by implying the attestor comparison default, though it does not elaborate on `expected_attestor` 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 (verifies) and a precise resource (a GBLIN Risk Attestation, the object returned by /api/x402/attestation, or a peer-attached proof-of-diligence). This object specificity cleanly separates it from sibling verify tools like receipts.verify and payments.verify without the agent 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?

It clearly tells the agent what inputs this tool accepts (the attestation object from the GBLIN endpoint or a peer proof-of-diligence) and notes it is free, which is a genuine routing signal. However it never states when NOT to use it or names an alternative verify tool, so exclusions are absent.

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?

Beyond the readOnlyHint, the description discloses meaningful behavioral mechanics: the vault does not self-rebalance and pays no external party, the Dutch auction ramps a premium from discount to cap, and the premium is the entire reward while nothing is paid out of the vault. This adds substantial context beyond the 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 three dense, purposeful sentences. It front-loads the core action, then explains the mechanism, then enumerates the returned fields. Every sentence contributes either to scoping or to behavioral understanding; there is 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?

For a zero-parameter read-only tool with an output schema, the description is complete. It specifies the network (Base), the resource (GBLIN rebalancing auction), the auction mechanism, the exact per-row return fields, and the reward economics. Nothing necessary 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?

The tool has zero parameters and the schema is empty, so the description need not explain parameters. Per the baseline for zero-parameter tools, the score is 4; the description appropriately focuses on output semantics instead.

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

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

The description opens with a specific verb and resource: 'Read the GBLIN rebalancing auction on Base.' It clearly identifies what the tool does and distinguishes it from sibling action-oriented tools by emphasizing read-only observation and returning state data rather than executing anything.

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 makes the use case clear: it is the tool for inspecting the current rebalancing auction state, including bidder-side calldata. It does not explicitly name alternatives or state when not to use it, but the read-only framing and detailed output description provide clear context without exclusions.

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?

Given annotations already declare read-only, open-world, idempotent, and non-destructive hints, the description adds value by clarifying the data source (self-observation, v0), the frequency (every 10 minutes), and the sealing mechanism (EAS attestation on Base). This goes beyond mere reputation and provides useful 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?

The description is concise at about 40 words, with all information relevant. It front-loads the core purpose (tallies) and then adds necessary detail. No wasted words.

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

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

The description is sufficient for a zero-parameter, read-only report with annotations and an output schema. It explains the data source, frequency, and sealing, but could offer a bit more on the exact contents of the report (e.g., what fields are included). However, given the output schema exists, the description need not detail return values, so this is adequate.

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 has zero parameters, so the description does not need to explain parameters. Since there are no params, the description's job is to set expectations, and it does so by describing what is included in the report. A baseline of 4 is appropriate because the description compensates for the lack of param details.

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

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

The description clearly states the tool's purpose: reporting kept/violated tallies for GBLIN's hash-pinned promises, with details on how data is collected (every 10 minutes) and sealed (EAS attestation on Base). It distinguishes itself from siblings by focusing on tallies and attestation, which is unique among the listed 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?

The description implies its use for checking compliance tallies and notes that it is self-observation only in v0, which gives context but does not explicitly state when to use this tool versus alternatives. It could benefit from mentioning that this is for read-only reporting, but the self-observation note provides some 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' is redundant. The added value is 'free' (cost profile) and the enumeration of what the document corpus contains, but auth/permission and error behavior are not covered.

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

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

Two tight sentences, front-loaded with the action and resource, then the corpus clarification. No filler sentences; every clause adds 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 values need not be explained, and annotations carry the safety profile; the description nonetheless names the returned fields and the document types. Complete enough for a single-parameter read tool, with only id-discovery guidance 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 schema even supplies an example id ('protocol-readme'), so the parameter is already well documented. The description adds little beyond confirming 'by its id'. 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?

States a specific verb and resource: fetch one GBLIN document by id, and clarifies the corpus (protocol docs, tool cards, live vault state). The singular 'one ... by its id' implicitly separates it from the sibling 'search', though that alternative is never named.

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 by the required id parameter, but there is no explicit when-to-use guidance, no mention of how to obtain an id, and no reference to the 'search' sibling that would supply one. The agent must infer the fetch-by-known-id workflow.

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, openWorldHint and destructiveHint=false, so the description's 'Read-only' is largely redundant. It does add one behavioral fact not in the annotations: supplying operation_id triggers additional operation-status reporting. Fails to mention that unspecified data is simply omitted (no leading check) or any auth requirements, so the value-add over structured fields is modest.

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 resource and the enumeration of fields, then the conditional branch. No filler, though the field list makes it dense enough that it reads as an inventory rather than a crisp summary.

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-format explanation is unnecessary, and the description still covers the data domain and the conditional branch. For a zero-required-param read tool this is nearly complete; only the routing relationship to sibling governance/protocol tools 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% and the parameter is fully documented in the schema (0x-prefixed 32-byte hex timelock operation id). The description adds only the effect of supplying operation_id ('it also reports the status of that timelock operation'), which is a mild supplement to schema-level meaning. Baseline 3 applies when the schema 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?

States a specific verb (Reads) and resource (GBLIN protocol governance) and enumerates exactly what is returned: vault ownership by the timelock, min delay/grace period, role member counts, and pending asset-addition proposals. This lets an agent distinguish it from sibling .state/.info tools like treasury.state, auction.state, and protocol.info 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?

Usage is implied (call to inspect governance/timelock state), and the conditional effect of operation_id is described, but the description never states when to prefer this over sibling tools such as protocol.info or treasury.state, nor any exclusions. Adequate but no explicit routing 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?

Annotations only declare readOnly/openWorld/destructive/idempotent hints, so the description carries the real behavioral burden and delivers: it discloses the return artifacts, the EIP-3009 signing flow, the front-running protection of 'receive', the relay fee behavior, and crucially that no private key is requested, held, or transmitted. That last point is exactly the kind of trust/security context annotations cannot convey.

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 non-redundant information; every clause about EIP-3009, x402, methods, and relay earns its place. It is a single long paragraph, though, and splitting the method/relay guidance from the security note would improve scannability.

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 7-parameter, enum-bearing tool with an output schema and annotations, the description supplies everything the structured fields cannot: the signing protocol, the two submission modes, relay semantics, and the no-private-key guarantee. Return values need not be detailed since an output schema exists, and what is given is more than sufficient.

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 genuine meaning beyond the schema: it explains why 'receive' resists front-running, why relay forces method 'transfer', and that the EIP-712 domain is read from the token rather than assumed. It does not restate the amount/validity parameters, which the schema already covers.

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: 'Builds a gasless GBLIN payment,' and immediately differentiates itself from siblings like payments.relay and payments.verify by describing exactly what artifact it produces (the EIP-712 message, calldata, and x402 payload). An agent can tell this is a preparation/signing-payload tool, not an execution or verification tool.

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 for the two methods ('receive' when only the recipient should submit, 'transfer' for an x402 facilitator) and for relay: true ('when nobody else will carry the payment on chain'). It stops short of naming the sibling tools it replaces or excludes (payments.relay, payments.verify), so routing against those is left to inference.

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 destructive=true, idempotent=true and openWorld=true, and the description adds substantial context beyond them: atomic Multicall3 settlement ('either both settle or neither does'), the fee denomination and pricing ('GBLIN at the live NAV'), and an explicit warning that it moves funds and uses the authorizations exactly as signed.

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, and every sentence contributes (scenario, input shape, atomicity, fee pricing, return, fund-movement warning). It is dense but not padded, though slightly long.

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 what an agent needs to invoke it correctly: the scenario, the exact signed-input shape, the all-or-nothing settlement semantics, fee denomination, and a fund-movement caution. Since an output schema exists, the brief note on the returned hash and outcome is sufficient.

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% with nested objects, so the schema carries the baseline. The description adds meaning beyond it by specifying that both objects are signed by the payer's wallet, that payment uses method 'transfer', and that the fee is priced at the live NAV.

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 ('relay carries a signed GBLIN payment on chain') and the distinguishing condition ('for a payer that holds no ETH'), which clearly separates it from payments.prepare and payments.verify among its 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?

Names the exact scenario that selects this tool (a payer with no ETH needing a gasless payment) and the inputs it expects. It does not explicitly route the agent away from payments.prepare/payments.verify or state prerequisites, but the context is clear enough to place it correctly.

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, destructiveHint=false, openWorldHint, so the safety profile is covered. The description adds substantial context beyond that: the exact on-chain checks performed, the ERC-1271 path for contract payers, the two possible return shapes (verdict + ready calldata vs failing reason), and the semantic meaning of 'would_settle'. This is rich, non-redundant behavioral disclosure.

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

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

Four sentences, all front-loaded with purpose and then the mechanics, with zero filler. The final sentence about the x402 facilitator earns its place by explaining what a 'would_settle' verdict actually licenses the agent to do.

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 detailed, yet the description still summarizes both return branches. Given the nested authorization object, the annotations, and the output schema, an agent has everything needed to call this correctly 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?

Schema description coverage is 100%, so the baseline is 3. The description implies the authorization object's contents (validity window, nonce, payer balance) and the EIP-712 signature origin, but adds no format or syntax detail for 'method', 'signature', or 'authorization' beyond what the schema already documents.

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: it checks a signed GBLIN authorization against the chain before gas is spent, and it enumerates the exact checks (EIP-712 signer recovery, ERC-1271 fallback, validity window, nonce, balance). An agent can tell it is a pre-flight verification step. It does not name the sibling it pairs with (payments.prepare / payments.relay), so the sibling differentiation is left 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?

'before any gas is spent on it' and 'the checks an x402 facilitator runs' give a clear context for when to call it, and the 'would_settle' verdict framing tells the agent what a positive result authorizes. No explicit when-not conditions or named alternatives (e.g. relay vs prepare) are given, so the guidance is clear but not exhaustive.

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 show readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that the output is plain text and lists contents, but it does not disclose any limitations, rate limits, or output details beyond what the annotations already convey.

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 sentence that is front-loaded with the core resource name and format, followed by a compact, useful list of contents. There is no redundant wording.

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

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

Given no parameters, an output schema, and simple annotations, the description is sufficiently complete for a protocol information fetch. The only notable gap is the lack of explicit usage guidance relative to sibling tools, which may still be inferred.

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 zero parameters and an empty input schema, the description carries the full semantic burden and does so by indicating exactly what kind of data will be returned. No parameter-level documentation is needed.

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 that protocol.info returns 'GBLIN llms.txt as plain text' and lists its contents: contract addresses, endpoints, prices, payment flow, and field contract of the attestation. This identifies the resource and distinguishes it from sibling tools like protocol.stats and receipts.get, though it lacks an explicit verb like 'retrieve'.

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 use when protocol-level information is needed, but it does not explicitly state when to use this tool versus alternatives or mention exclusions. For a simple zero-parameter read, this is adequate but not fully explicit.

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

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

Annotations already flag read-only, open-world, idempotent, and non-destructive behavior, so the description only needs to add non-obvious context. It adds 'Cached 5 min' (stale data window) and 'methodology disclosure', which are useful beyond structured annotations. No contradiction with 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?

Two short sentences front-load the counters and add only the cache and methodology caveats. No filler, no repetition of schema or annotations.

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

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

An output schema exists, annotations are rich, and no parameters require explanation. The description covers data scope, freshness via 'Cached 5 min', and methodology disclosure. This is complete for a no-input stats 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 and the schema is fully self-describing with additionalProperties false. The description therefore does not need to explain inputs. Baseline 4 applies.

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

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

The description opens with 'Cumulative public counters of GBLIN's x402 endpoints' and enumerates paid calls, unique payer wallets, USDC earned, and methodology disclosure. This clearly identifies the tool as an aggregate stats endpoint, distinct from receipt/risk/info siblings. The metric scope is unambiguous.

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

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

The 'cumulative public counters' phrasing and 'Cached 5 min' note establish when this tool is appropriate: for aggregate, quick, read-only metrics. It does not explicitly name alternatives, but no exclusions are needed for a zero-parameter stats endpoint. The context is clear enough for selection among siblings like receipts.get.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuine context beyond those hints: it discloses that the receipt is re-signed with a fresh inclusion proof, explains why re-signing yields deterministic output ('Ed25519 is deterministic'), notes the response includes the current signed checkpoint and latest on-chain anchor, and states it is free. This gives the agent useful behavioral expectations without contradicting the 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 one dense sentence plus 'Free.', with the core resource (receipt from the log) front-loaded. Every phrase earns its place — re-signing, inclusion proof, checkpoint, anchor — and the parenthetical on Ed25519 determinism explains a non-obvious property. Slightly telegraphic, but appropriately sized with essentially no waste.

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

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

The tool is simple (one required parameter, fully described in schema), has an output schema so return format need not be spelled out, and annotations cover the safety profile (read-only, idempotent, non-destructive). The description enriches this with the response contents and cost. Missing only minor context like rate limits or what GBLIN's log is, which are not necessary for correct invocation.

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

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

Schema description coverage is 100%: the 'index' parameter is fully documented in the schema ('Receipt index in the log (0-based; current size at GET /log/checkpoint)'). Per the baseline for high schema coverage, the description need not repeat parameter details; its 'Receipt #index' phrasing aligns with the schema. The description adds no new parameter semantics, but none are required.

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 specifies the resource precisely — a receipt from GBLIN's receipts log — and enumerates what is returned (re-signed receipt, inclusion proof, signed checkpoint, on-chain anchor). The annotation title 'Get a receipt by index' supplies the explicit verb. It is clear what the tool does, though the description itself reads as a noun phrase and does not explicitly contrast with the related siblings receipts.seal and receipts.verify.

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 offers no guidance on when to use this tool versus alternatives. Siblings like receipts.seal and receipts.verify are functionally adjacent, but the description never says 'use this to fetch an existing receipt; use receipts.verify to check one' or any exclusion. Nothing is misleading, but the agent is left to infer the usage context.

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 only cover readOnly/openWorld/idempotent/destructive; the description adds far more: self-reported provenance limits ('proves the record existed, not that the action happened'), that action/agent_id/tool/meta are published verbatim, demo:true marking, rate limits, and that unlisted fields are ignored. This is exactly the disclosure an agent needs before writing to a public log.

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 the tool does, then the returned receipt, then operational constraints, then caveats. Every sentence carries distinct information — no repetition of the title or name, no filler despite the density of jargon.

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 non-idempotent write into a public transparency log with an output schema present, the description covers the safety-relevant behavior (publishing, irreversibility implied by appending to a log, rate limits, provenance caveat) while correctly leaving return-value structure to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the privacy consequence of each PUBLISHED field and confirming that fields outside the schema are silently dropped. It doesn't clarify hash formatting or mode behavior beyond what the schema already 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?

Specific verb ('appends hashes... to a transparency log') plus a precisely enumerated artifact set (Ed25519 signature, inclusion proof, C2SP checkpoint, EAS anchor). This clearly distinguishes it from siblings receipts.get and receipts.verify, which read/check rather than create.

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 real context: demo-only over MCP, 5 seals/day/IP, and names the alternative channel (paid x402 HTTP endpoint) for unlimited use. It stops short of routing to the sibling tools that consume a receipt (receipts.get, receipts.verify), so it's clear context without full alternative mapping.

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 substantial context beyond the annotations: it works purely offline on math, performs no log lookup, and does not trust this server. It also names the reference implementation (verify-receipt.mjs) with the same checks, and points to a distinct endpoint for a different class of check — far richer than the readOnly/idempotent hints alone.

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

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

Two front-loaded sentences: the verb and its guarantees come first, the check list and the alternative endpoint follow. The check enumeration is dense but each item earns its place by telling the agent what is validated.

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

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

An output schema exists, so return values need no explanation, and with one fully described parameter the description only had to cover behavior and scope — which it does, including what it does not do and where the complementary check lives.

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?

One parameter with 100% schema description coverage; the schema already explains the receipt object and its bare-or-wrapped form. The description adds no syntax or format detail beyond that, 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 resource ('Verifies a gblin-receipt/v1 JSON') and enumerates the exact cryptographic checks performed (leaf hash, Ed25519 signature, RFC 6962 inclusion proof, C2SP checkpoint signature, verifier-key hash). This clearly separates it from siblings like receipts.get (fetch) and receipts.seal.

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 delimits scope: it does the math without a log lookup and without trusting the server, and tells the agent where the separate on-chain consistency check lives. It does not, however, mention the other verification-style siblings (attestation.verify, payments.verify) or state that a receipt must first be obtained, so routing guidance is clear but not exhaustive.

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 the read-only, idempotent, non-destructive, open-world profile, so the bar is lower. The description still adds material behavior: the artifact is static and permanently expired and matches the signed schema, which tells the agent the data is a non-live fixture rather than a valid credential.

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 key qualifier (static, permanently expired, sample:true) front-loaded and no filler. 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-value documentation is unnecessary. For a zero-parameter fixture, the description supplies everything an agent needs: what it returns, how it relates to the signed attestation, and why it exists.

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 to disambiguate and the baseline of 4 applies. The description correctly implies the tool is a parameterless fetch of a fixed artifact.

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

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

The description states precisely what the tool returns: a static, permanently expired sample of the signed Risk Attestation, marked sample:true, carrying the same fields and EIP-712 schema as the real one. An agent can instantly distinguish this fixture from the signed attestation and from verification siblings like attestation.verify.

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 names the intended use case: building and testing parsers and verifiers. It does not explicitly state the exclusion (do not treat this as a valid attestation for production verification), though 'permanently expired' strongly implies it.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuine operational context beyond that: the data source (GBLIN's on-chain Crash Shield on Base), a 60-second cache freshness bound, and the free/unsigned versus paid/signed trust trade-off.

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

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

Two tight sentences with no filler: the first front-loads what is returned and the allowed values, the second front-loads the cost/trust model. Every clause carries information an agent needs.

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 explain the return shape, and it instead supplies what the schema cannot: provenance, cache TTL, and the free-versus-paid boundary. Nothing required to call a zero-arg tool 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly avoids inventing parameter semantics and instead spends its words on the data 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?

The description names a specific resource (BTC/ETH risk regime plus matching risk posture) and enumerates the exact return domain (calm | elevated | crash), so an agent knows precisely what it yields. It also implicitly separates itself from sibling risk.attestation_sample by describing a live read rather than a sampled attestation.

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 a clear selection rule between this free, unsigned live read and 'a separate paid x402 HTTP endpoint' for offline-verifiable signed data. It lacks an explicit pointer to sibling tools such as risk.attestation_sample, so it is clear context without full exclusions.

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, destructiveHint=false and openWorldHint=false, so safety is covered structurally; the description still adds cost context ('free') and the key behavioral detail that returned ids map to full documents (implying a separate retrieval step). It does not disclose rate limits or result-count/pagination behavior, so 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?

Two sentences, verb-and-scope front-loaded, with the indexed content enumerated in a single compact list and the return shape appended last. Every clause adds discriminating information about what this tool searches.

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 the return shape needn't be re-explained (though it is), and annotations carry the safety profile, leaving the description to cover scope and content, which it does thoroughly. The only gap is the absence of explicit routing guidance to the sibling retrieval 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 a single parameter ('query') at 100% schema description coverage, so the schema already carries the meaning and the baseline is 3. The description does not add syntax, format, or example guidance beyond the schema's 'plain words' 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?

States a specific verb (searches) and a precisely scoped resource (GBLIN's documentation and live state), then enumerates exactly what is indexed: agent API summary, protocol README/governance/deployments/review record, MCP server and library READMEs, public pages, one card per MCP tool, and live vault state. This is far more specific than the sibling tool names, so an agent can tell it is the general retrieval entry point rather than a domain-specific state tool.

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: it is the general documentation/state search, and the note that each id identifies a full document hints at a follow-up fetch, but no explicit when-to-use, when-not-to-use, or named alternative (e.g. the 'fetch' sibling) is given. An agent must infer the 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: it performs an external live-gas-price check (consistent with openWorldHint) and it discloses pricing behavior — free by default, with a 0.003 USDC charge only when MCP_PAYWALL=true. That paywall disclosure is valuable and not derivable from the 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?

Three sentences, front-loaded with the core analysis, then the conditional daily_burn_usd behavior, then the pricing caveat. Every clause carries distinct information — no filler, no repetition of the title or 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers purpose, the external-data dependency, and the paywall, leaving little an agent would need before calling it. A note on prerequisites (e.g. a funded wallet) is the only minor omission.

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 schema already documents all three parameters. The description adds real meaning beyond the schema for daily_burn_usd: it explains that supplying it produces days of USDC runway and a 7-day-spend-preserving split that treats only the surplus as a GBLIN candidate, which is more than the schema's terse 'Average daily spend in USD'.

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 (agent wallet treasury) and enumerates exactly what it reports: GBLIN/USDC/ETH balances, ETH exit coverage at live gas price, and redemption cooldown. This is far more than a restatement of the name. It does not, however, explicitly differentiate itself from close siblings like treasury.state or treasury.nav_history, which an agent could plausibly confuse with it.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative sibling is named. The description explains the conditional effect of daily_burn_usd but never tells the agent when this tool is the right pick over treasury.state, treasury.plan, or treasury.quote.

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 genuine behavioral context beyond that: values are read from the chain at past blocks, the series begins at vault deployment, and it computes window change and largest drawdown. It stops short of noting rate limits or pagination, so 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 sentences, front-loaded with what the series contains before moving to provenance and comparison use. Dense but every clause carries information; no obvious 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?

An output schema exists, so return-shape explanation is not strictly required, and annotations cover safety. The description supplies provenance, series start, and benchmark framing, leaving only minor gaps around pagination or point limits for a read-only tool.

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

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

Schema coverage is 100% and both parameters (points, interval) are fully documented with defaults in the schema, so the baseline is 3. The description only vaguely gestures at the window via 'change of each over the window' and adds no syntax or default meaning 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 specifies a concrete verb and resource: it returns the NAV per GBLIN share over time, enriched with the ETH/USD and BTC/USD oracle prices the vault uses plus change and drawdown. This is far more specific than a sibling like treasury.state could be, though it never explicitly names a sibling to distinguish itself from.

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: the agent learns the history starts at vault deployment and can be benchmarked against holding ETH or BTC. There is no explicit when-to-use versus alternatives (e.g., treasury.state for current values) and no exclusions, so guidance is only implied.

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 (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds substantial behavioral context beyond them: the exact operating-cash formula, that fees are read live from the vault, that exit value and round-trip cost are estimated, and the named blockers (Crash Shield, redemption cooldown, ETH for the exit). The closing caveat that GBLIN is crypto exposure rather than cash or yield is a genuine behavioral disclosure an agent needs.

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 and the read-only guarantee are front-loaded, and the middle enumerates plan contents efficiently. The single sentence is dense and becomes run-on, but each clause carries information an agent would otherwise have to infer from an output 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?

For a five-parameter, read-only simulation tool with an output schema present, the description supplies everything missing: the derivation of operating cash, the scope of the simulation, and the risk caveat about GBLIN. Return-value detail is correctly left to the output schema.

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 relational meaning the schema cannot: operating cash = max(reserve_usd, daily_burn_usd × days), and that trial_usdc simulates alongside the surplus using the 100 USDC default. It clarifies how the parameters interact rather than just restating them.

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 immediately distinguishes itself from the sibling simulations by naming exactly what the plan contains (operating cash, surplus, mint simulation, trial, blockers). An agent can tell this apart from treasury.quote or treasury.state 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?

The description gives clear context for when this applies — idle USDC above operating cash — and states 'Read-only: nothing is executed and nothing is advised,' which frames the decision-support role. It does not explicitly name when to prefer treasury.quote or treasury.state instead, so the alternative routing is implied 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses meaningful behavior: it returns expected output, a safe minOut with a dynamic slippage buffer (2.5% normal / 4% during Crash Shield), and a fee breakdown. This adds real context about what the call yields and its side-effect-free nature, with no contradictions.

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 front-load the core purpose and then pack in return values, slippage policy, and fees without wasted words. The 'Read-only' tag is redundant with annotations but harmless and brief.

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 tool has only two parameters, an output schema, and strong safety annotations, the description supplies all necessary behavioral context: non-execution, direction semantics, slippage policy, and fee reporting. Nothing an agent needs to choose or invoke 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?

The description adds meaning to the direction enum by defining buy as ETH→GBLIN and sell as GBLIN→ETH, which complements the schema's amount_in note. With 50% schema description coverage, this mapping meaningfully reduces ambiguity, although the description does not explicitly re-explain every 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?

The description opens with a precise verb and scope: 'Preview a buy (ETH→GBLIN) or sell (GBLIN→ETH) without executing.' It clearly differentiates itself from execution-oriented siblings by stating it does not execute and is read-only, and the title reinforces the quote/mint/redemption purpose.

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 context: use this tool when you need a non-executing preview of a mint or redemption quote. It does not explicitly name alternative tools or say when not to use it, but 'without executing' and 'Read-only' are strong usage signals that prevent confusion with execution 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description goes slightly beyond that by flagging that the response includes a NAV reliability indicator, which hints at degraded/uncertain states, but it adds no auth, rate-limit, or freshness/staleness 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?

A single dense sentence that front-loads the verb and resource, then lists the concrete payload fields. Every clause earns its place with no boilerplate or repetition of the title.

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

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

An output schema exists, so enumerating return values in more detail is unnecessary, and annotations carry the safety profile. For a zero-argument read tool this is essentially complete, with the only gap being the absence of sibling-routing guidance against treasury.health and treasury.nav_history.

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 argument semantics to document; per the baseline for parameterless tools this scores 4. The description correctly does not invent parameters and instead spends its text on what the call returns.

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 ('GBLIN protocol state on Base mainnet') and enumerates the returned fields (NAV in USD, basket composition with dynamic weights, Crash Shield status, NAV reliability). The temporal qualifier 'current' implicitly distinguishes it from the historical sibling treasury.nav_history, but it never explicitly differentiates from treasury.health or protocol.info.

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?

No explicit when/when-not guidance or named alternatives. Usage is only implied by the word 'current', which signals this is the live-state reader rather than the history tool (treasury.nav_history) — enough for a hint, not for confident routing among the many treasury.* and protocol.* siblings.

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