SqueezeOS — Institutional AI Market Intelligence

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false, openWorld=true), it discloses that the caller's payload is forwarded as PAYMENT-SIGNATURE, that SML never signs or spends, that settlement of USDC is irreversible, that a receipt is persisted, that the stored job stays immutable, and the fallback behaviors (fresh 402 on missing auth, structured error on bad job_id). This is exactly the behavioral context the 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?

Purpose and precondition are front-loaded, and most sentences carry real information (auth forwarding, irreversibility, error paths, example). It is slightly dense and repeats the receipt concept ('persists a receipt' / 'PAYMENT-RESPONSE receipt'), keeping it out of the top band.

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 mutating settlement tool, the description covers the auth model, irreversibility, error handling, and delivery artifacts, and an output schema exists for return values. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema (including the job_id pattern/format and the payment_response role). The description restates rather than extends that, so baseline 3 is correct.

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 (accept / settle delivery) and resource (one immutable job) and pins it to the x402 authorization flow, letting an agent distinguish it from siblings like aftersearch_quote or aftersearch_verify_serp. The purpose 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?

It gives a clear precondition — 'use this when an agent holds fresh PAYMENT-REQUIRED terms and the caller approves the spend' — which tells the agent the state required before calling. It does not explicitly name the sibling (e.g. aftersearch_quote) that produces those terms or state when-not-to-use, so it stops just short of full 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 already declare readOnly, idempotent, and non-destructive, and the description partly restates that ('Read-only and idempotent; no side effects'). It goes beyond annotations by disclosing error behavior ('structured job_not_found error' on unknown job_id), the freshness/dynamic nature of the terms, and the quote-vs-payment semantic.

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 the trigger condition, then return fields, error behavior, and an example. Mostly efficient, though 'Read-only and idempotent; no side effects' is redundant with the annotations and adds length without new 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?

A single required, fully specified parameter, complete annotations, and an output schema mean the definition need not explain return values. The description still covers purpose, trigger, error case, and semantics, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single job_id is fully documented with pattern and source. The description reinforces the source of the id ('returned by aftersearch_resolve') and adds the 'exact job only' scoping, but adds little syntax or format detail beyond the schema, so the baseline of 3 holds.

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 (Return) and resource (fresh x402 PAYMENT-REQUIRED terms for one immutable job), including the exact fields returned (USDC price, pay_to, network, asset). It is clearly distinguishable from siblings like aftersearch_accept and aftersearch_resolve.

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

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

Explicitly names the precondition ('when an agent holds a job_id') and the decision context ('needs the current USDC price and payment instructions before deciding to pay'), and contrasts with the payment step by noting 'a 402 challenge is a quote, never payment'. The example ties it to aftersearch_resolve as the job_id source.

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 the annotations: it discloses that each call creates one server-side job record (a side effect, consistent with readOnlyHint=false and idempotentHint=false), guarantees no funds are spent or moved, and specifies the failure mode (structured input_rejected instead of a job). This is exactly the extra 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 transformation, then behavior and error semantics in descending priority. Slightly redundant between the opening purpose sentence and the 'Use this when...' sentence, but no padding overall.

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 it wisely avoids detailing return fields, yet still covers what an agent needs that the schema does not: the per-call job-record side effect, the no-funds guarantee, immutability of the job, and the input_rejected error path. Nothing material is missing for a pre-payment compile step.

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% for the single parameter, so the schema already defines the query and its length bounds. The description only restates it as a natural-language question, adding no new syntax, format, or constraint detail; 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 concrete transformation: natural-language query -> machine intent + Evidence Pack + one immutable x402 job with a fresh quote pointer. The 'before any payment' framing and the example ('whether a token contract is safe') let an agent distinguish this from the quote/accept 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?

Explicitly names the condition for use ('when an agent needs to turn a what-would-I-Google question into a priced, quotable evidence job before any payment'), which positions it ahead of the settlement-oriented siblings. It stops short of naming the alternatives (aftersearch_quote, aftersearch_accept) or stating when NOT to use 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 only declare readOnly=false, destructive=false, idempotent=false, openWorld=true. The description adds context the annotations cannot: an immutable job record is created per call (explaining the non-readOnly hint), the tool never spends, it may fetch only the single caller-provided URL, and unreachable sources yield a structured source_unavailable error instead of a verdict.

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 verb and resource, then layers side effect, cost, and error behavior; every sentence carries information. It is slightly dense — four stacked clauses plus an example — but nothing is padded.

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 (so return values need not be described), it still names the verdict and source fields, and it covers the mutation side effect, the zero-cost guarantee, the URL-fetch scope, and the error path. An agent has everything needed to call it 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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents length bounds and the 'no Google scraping' constraint. The description restates the same input modes ('pasted SERP or AI-answer text, or one caller-provided public URL') without adding new syntax or format guidance, 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 (verify) and resource (pasted SERP/AI-answer text or one caller-provided public URL) and names the outcome (confirm/contradict/missing verdict with cited sources). It implicitly but clearly distinguishes itself from the paid-evidence siblings by contrasting with 'before quoting or paying for evidence' and 'never spends'.

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 states when to use it: 'when an agent needs a confirm, contradict, or missing verdict with cited sources before quoting or paying for evidence,' and adds a concrete example (checking a token launch date claim). It does not name the sibling tools (e.g., aftersearch_quote) as alternatives, so the routing is implied by cost 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?

Goes well beyond the annotations by spelling out the payment flow: an unsigned call returns the live x402 PAYMENT-REQUIRED challenge and never auto-spends, whereas supplying a challenge-specific signature authorizes exactly one paid, irreversible USDC settlement on Base. It also states that errors return a structured error, which the schema and annotations do not.

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

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

The core capability and the unsigned-vs-signed split are front-loaded, and no sentence is filler. It is fairly dense and the payment mechanics arrive in a long middle block, but the length is justified by the security-sensitive behavior being described.

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-parameter tool with a full output schema, the description covers everything an agent needs: what is fetched, the truncation bound, the two distinct call modes, the payment/authorization semantics, and error behavior. Return-format details are 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 real meaning: it ties the return size explicitly to max_chars and constrains payment_signature to a 'challenge-specific' value that should only be retried after receiving the challenge. It does not clarify URL host/redirect handling beyond 'public HTTPS'.

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 (fetch), resource (LLM-ready Markdown from any public HTTPS URL) and the mechanism (SML Clean Web Reader). It is clearly distinguishable from the sibling tools, which cover capability discovery, x402 contract/evidence, and quoting rather than raw page conversion.

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 a concrete usage context (grounding a research answer, e.g. fetching a documentation page before summarizing) and the key precondition that no separate SML account or API key is needed. It does not name an alternative sibling tool to use instead in overlapping scenarios, so it falls just short of explicit 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so 'Read-only and idempotent; no side effects' largely repeats structured data. It does add genuinely new behavior: the manifest is regenerated from the live route table and errors return a structured error object, but that is a modest increment.

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

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

Front-loaded with the core action and source of truth, and each later sentence maps to usage or behavior. Slightly redundant ('canonical' twice, and the read-only/idempotent/no-side-effects triple restates annotations), costing it a point.

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

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

An output schema exists and the description correctly does not re-document return values, instead covering use case, provenance, error behavior, and caching guidance. For a zero-parameter read with full annotation coverage, nothing an agent needs 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 of 4 applies. The description correctly implies a parameterless, no-argument read and adds no misleading argument expectations.

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 ('Read the canonical machine capability manifest') and adds provenance ('generated from the live Flask route table'). It contrasts itself with the one-by-one query pattern, which implicitly separates it from siblings like discover_capabilities or inspect_capability, though it never names those siblings explicitly.

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 a clear when-to-use condition ('when an agent needs the authoritative full inventory ... instead of querying tools one by one') plus a concrete pattern ('fetch it once at session start to cache the product catalog'). No explicit when-not-to-use or named alternative tool, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description still adds real value beyond them: it confirms the atlas returned is live, discloses that error cases return a structured error, and notes the related paid endpoint and its $0.001 USDC cost so the agent doesn't confuse discovery with the chargeable check.

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 content of the atlas are front-loaded in the first sentence, and each subsequent sentence carries distinct information (trigger, return, side-effect profile, exclusion, error behavior, example). It is slightly padded by 'Read-only and idempotent; no side effects', which largely restates the annotations, and the example sentence is optional.

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?

Output schema exists, so return-value description is unnecessary; the description instead covers everything else an agent needs for a zero-parameter read tool: what is returned, when to call it, that it is free and side-effect-free, how to interpret the paid alternative, and how errors surface.

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. There is nothing for the description to clarify beyond confirming that the atlas is returned wholesale rather than filtered by caller-supplied criteria.

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 (list) and a precisely scoped resource (the SML Commit effect atlas), then enumerates what the atlas contains: registered actions, target systems, owners, and caps. An agent can distinguish this discovery/read tool from siblings like commit_read_terms or aftersearch_quote without opening any schema.

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

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

Gives an explicit trigger ('when an agent needs to quote or validate a commit check and must cite the exact registered effect terms'), a concrete example (checking whether a cron change is committable), and an explicit exclusion: it never calls the paid check itself, which routes the agent to the POST /v1/commit path. Both when-to-use and when-not-to-use are covered.

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, and the description partly repeats those. It earns credit for adding behavior beyond the annotations: it returns the terms document and returns a structured error on failure, which the annotations do not 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, then usage, then behavior, and it stays short. The closing example sentence and the restated 'read-only and idempotent; no side effects' are mildly redundant given the annotations, costing a point.

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

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

With an output schema present, the description need not explain the return shape, and it covers what the tool does, when to call it, and error behavior. It would be fully complete if it positioned itself relative to adjacent commit/x402 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 nothing for the description to disambiguate and the baseline is 4. The description correctly implies no input is needed to fetch the terms.

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 (read) and resource (SML Commit terms) and enumerates what it contains: price, decision outcomes, and rules. It is clearly distinguishable from siblings like commit_discover_effects or x402_contract, though it never names an alternative explicitly.

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 usage context: 'use when an agent needs the exact commit-check terms to quote to a caller before any payment,' and the example reinforces the pre-quote timing. It offers no explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations already cover readOnly/idempotent/destructive, but the description adds meaningful traits: metadata is real, no fabricated composite score, a real liveness probe, and structured errors. It also states what is returned is the same endpoint/payment fields as inspect_capability, which goes beyond the annotation set.

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 usage, and most sentences earn their place. 'Read-only and idempotent; no side effects' largely restates the annotations, which is the one mildly redundant sentence.

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, return values need no elaboration, and the description still clarifies the shape of results (same fields as inspect_capability). Usage, error behavior, and safety are all covered for a 2-parameter read tool.

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

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

Schema coverage is 100% and both parameters are documented in the schema (sml_ids 2-5, probe default true), so the schema carries the load. The description only implicitly gestures at the probe via 'live'/'real metadata' without explaining the boolean switch or its cost/latency implication.

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 (compare), resource (live SqueezeOS capabilities), and scope (2-5, side by side, real metadata). It distinguishes itself from the single-target sibling 'inspect_capability' by naming what it returns relative to that 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 context ('when an agent must choose between similar APIs, for example weighing price against coverage') plus a concrete scenario ('compare two web-reader capabilities before routing a research task'). It does not explicitly name when to use inspect_capability or recommend_capability instead, so it stops short of full 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the safety profile is covered; the description usefully adds mode behavior ('lexical mode is always available and unified mode may add evidence-backed semantic context without fabricating scores') and error semantics ('returns a structured error instead of results'). The clause 'Read-only and idempotent; no side effects' merely restates annotations, earning no extra credit, but the mode and error disclosure is genuine added value.

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

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

Purpose is front-loaded in the first sentence, followed by usage, return shape, safety, error behavior and a worked example in a compact block. Nothing is off-topic, though the safety sentence duplicates annotation content and could be trimmed.

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 detail return structure, and it correctly focuses on routing (when to use), mode selection and failure behavior. The only gap is that the closest sibling discovery tools are never mentioned, leaving the agent to infer the boundary from the name alone.

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 nevertheless earns a bump by explaining the practical difference between the two mode values ('lexical' always available vs 'unified' adding evidence-backed semantic context without fabricating scores) and by giving a concrete query example with its x402 pricing angle. It adds meaning beyond the raw enum/default text.

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

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

States a specific verb+resource: 'Search the live SqueezeOS capability inventory by keyword', plus the downstream intent ('find which SML APIs exist for a task'). It is clearly distinguishable from siblings like execute_capability or inspect_capability, but it never names the closest discovery alternatives (capability_manifest, recommend_capability), so the 5-level sibling differentiation bar is not met.

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?

'Use this when an agent needs to find which SML APIs exist for a task before calling anything' gives an explicit trigger condition. It does not state when NOT to use it or name recommend_capability/capability_manifest as alternatives, so it stops short of the 5-level when/when-not/alternative triad.

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 destructive/openWorld/non-idempotent, and the description adds genuinely new context beyond them: that execution may create records or settle an authorized fee, that the server never signs wallets, that off-host and operator routes are denied, and that an unsigned call returns an x402 challenge. This is exactly the behavioral detail 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?

The write-gate and return behavior are front-loaded, and each sentence carries information (denials, payment, API schema link). It is dense with domain jargon (SML, x402, SqueezeOS) that slightly taxes first-read parsing, but there is no redundant 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 detail return values, yet it still sketches the two outcomes (target result or x402 challenge). Combined with auth/fee handling, denial rules, and a link to the API schema, an agent has everything needed to invoke it safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: confirm_write is a write authorization gate, payment_signature is caller-signed and authorizes the published SML service fee (server does not sign), and the path must be a concrete public path rather than a full URL. It goes beyond restating the schema fields.

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

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

The description states a concrete verb and resource — 'Execute one public SqueezeOS REST path with POST' — and constrains scope to public paths while denying operator routes and off-host URLs. It is clear what the tool does, though it never names the sibling it competes with (e.g. call_capability / read_capability), so differentiation is inferred from scope rather than stated.

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 hard prerequisite ('after confirm_write=true'), notes that a caller-signed payment_signature may be needed to settle the published fee, and discloses that operator routes and off-host URLs are rejected. No explicit alternative tool is named for when this is the wrong choice, so it falls short of full when/when-not guidance.

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

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

Annotations are thin (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description carries real weight and delivers: an unsigned call returns the live x402 PAYMENT-REQUIRED challenge (USDC on Base) and never auto-spends; retry only with a challenge-specific signature; missing chain/spot/OI yields a not-available result with nothing charged; a supplied signature authorizes one paid, irreversible settlement. These are exactly the cost/side-effect facts an agent needs before calling.

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

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

Front-loaded with the core capability, then payment mechanics, then the not-available case and a disclaimer. Dense but nearly every sentence carries a distinct fact; the risk is mild over-length rather than waste, and the disclaimer line is arguably marginal but defensible for a paid financial tool.

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

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

Given a 2-parameter schema, an existing output schema, and sparse annotations, the description covers the remaining unknowns: what is returned, the x402 payment lifecycle, failure behavior, and settlement irreversibility. An agent can decide to call, understand cost, and know how to retry without consulting anything else.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: payment_signature must be bound to the exact challenge, using it triggers a single irreversible settlement, and only a challenge-specific signature should be retried. The symbol parameter is left to the schema, which documents it adequately.

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 dealer gamma-exposure and pin-risk map for one US ticker from live Tradier option chains, then enumerates the concrete outputs (long/short gamma regime, zero-gamma flip line, call/put walls, max-OI pin strike, per-strike GEX ladder). This is clearly distinguishable from siblings like ticker_dossier or aftersearch_quote, which do not deal with dealer positioning.

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 a clear trigger ('when an agent needs to know where options dealers are forced to hedge, e.g. before judging whether a move is dampened or amplified') and a concrete scenario ('check SPY's zero-gamma line before the open'). It also encodes the retry rule for unpaid calls. It stops short of naming an alternative sibling or stating when NOT to use it, so it is strong context rather than explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the restated 'Read-only and idempotent; no side effects' sentence earns little. Beyond that, the description adds real behavioral context: the probe is a genuine liveness check rather than a fabricated reliability score, and errors return a structured error object.

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

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

Purpose and usage condition are front-loaded in the first two sentences, and the concrete example at the end is genuinely useful. It is slightly padded: the read-only/idempotent sentence duplicates annotations, and 'On error, returns a structured error' is close to a tautology.

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, and the description covers purpose, precondition, behavior, and error handling. The only meaningful gap is not routing the agent to a sibling when the capability is not yet identified.

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 both sml_id and the probe boolean with its default. The description mentions the liveness probe but adds no syntax, format, or cost guidance beyond what the schema provides, 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 a specific verb and resource ('Inspect one live SqueezeOS capability by its sml_id') and scopes it to a single capability rather than a set. It implies differentiation from the discovery/compare siblings ('when an agent has a candidate capability'), but never names an alternative tool, so it stops short of full sibling separation.

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 triggering condition: use it when a candidate capability is already in hand and its endpoint, parameters, and x402 payment terms are needed before calling. It does not, however, name the nearest alternative (e.g. read_capability or x402_contract) or state when this tool is the wrong choice.

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 readOnly/idempotent/destructive, but the description adds genuinely new behavioral context: results are capped at 10, prices are Google list prices from the 2026-10-09 catalog export and are not payable here, USDC is not accepted, and no PDF is returned. That is far more than the annotations 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 the core action and return shape, then constraints. Slight redundancy in the three-part negative listing ('does not sell... does not return the PDF... will not accept USDC'), but every sentence carries usable information for an agent.

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 read-only search tool with an output schema and full annotation coverage, the description supplies everything needed: scope, result fields, result cap, price caveat, and the handoff action. Nothing required to call 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 the schema already documents job (1-500 chars, example) and limit (1-10, default 10). The description adds value by supplying several concrete example job strings and reinforcing the 10-title cap, which helps an agent shape a correct call.

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 (filter) and resource (public ScriptMasterLabs Google Play book catalog) with concrete example queries ('x402 payments', 'options trading'). It also carves out what it is not (a store, a PDF delivery, a USDC payment endpoint), which cleanly separates it from the purchase/x402 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?

Gives clear when-to-use (reader is working on a job) and when-not (buying the book, getting the PDF, paying USDC), plus an explicit handoff instruction: give the human the google_play_url. It stops short of naming a specific sibling tool as the alternative for purchase, so it is not a full 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 destructiveHint=true and idempotent=false, and the description reinforces this with 'May settle an irreversible published SML service fee.' It adds genuinely useful non-schema behavior: 'Cannot change the HTTP method or send a request body,' 'The server never creates wallet signatures,' and that operator/off-host routes are denied. It does not cover rate limits or auth failure handling, keeping it short of a 5.

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

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

The text is front-loaded with the core action and then layers constraints and effects in short sentences that each carry information. It is jargon-dense but no sentence is wasted; a minor deduction for density that slightly burdens parsing.

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, return values need not be detailed, yet the description still notes delivery and payment-response evidence. Combined with annotations and the openapi schema link, the definition gives an agent enough to call this complex paid tool correctly, though failure-mode detail is thin.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the concrete-path and x402-signature semantics. The description adds only tangential context ('caller-signed authorization for that exact resource's fresh x402 challenge') rather than new per-parameter meaning, 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 states a specific verb and resource: 'Retrieve one paid SqueezeOS REST path with GET.' It distinguishes the tool from sibling read/call tools by emphasizing the paid, x402-challenge-signed nature. It stops short of naming a specific sibling it replaces, so it is clear but not fully differentiating.

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

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

Usage is implied through the payment/x402 framing and the 'alternative_intent' fallback after an unsigned HTTP 402, which hints at the flow. However, no explicit when-to-use or when-not-to-use guidance against the many capability siblings (read_capability, call_capability, execute_capability) 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?

Annotations already cover readOnly/idempotent/openWorld/non-destructive, and the description adds substantial context beyond them: it rejects payment authorization, bodies, and non-GET methods; returns either data or the unchanged unpaid x402 challenge with no-spend alternatives; never signs or settles; and denies operator routes and off-host URLs. This is rich disclosure of runtime behavior and 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 the core operation, then a series of short, information-dense sentences covering constraints, return behavior, and the schema URL. Nothing is padding, though the run of negative statements is slightly packed.

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, rich annotations, and 100% schema coverage, the description need not restate return values; instead it supplies the routing/safety constraints (no signing, no operator routes, off-host denial, x402 challenge handling) that an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the concrete-path and alternative_intent semantics. The description adds no syntax, format, or ranking detail beyond what the schema provides, so the 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+resource: read one public SqueezeOS REST path via GET. This is far clearer than a tautology and scopes the operation tightly, but it does not explicitly name or contrast with close siblings such as call_capability, execute_capability, or purchase_capability_read, so 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?

The negative constraints ('Cannot accept payment authorization, a request body, or another HTTP method') imply when this tool is not appropriate and the mention of 'no-spend alternatives' hints at the payment-free use case. However, no sibling is named and there is no explicit when-to-use vs. when-to-use-an-alternative statement, so guidance remains 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?

'Read-only and idempotent; no side effects' merely restates the annotations and earns no credit. The added value is genuine though: it discloses the return contents (ranked capabilities with live endpoint and x402 payment metadata plus suggested next actions) and error behavior ('returns a structured error'), which annotations do not cover.

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

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

Front-loaded with the purpose, then use condition, then return/error behavior; the two examples aid selection. The sentence 'Read-only and idempotent; no side effects' is redundant against the annotations and does not earn its place.

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

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

With an output schema present and rich annotations, the description does not need to explain result shapes in full, and it correctly focuses on selection guidance plus runtime metadata. It is complete enough for a 2-parameter read-only recommender, missing only sibling disambiguation.

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 both parameters are fully documented in-schema (query length bounds, limit range and default), so the baseline is 3. The description adds no syntax or semantics 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?

The description gives a specific verb and resource ('Return the best-matching SqueezeOS capabilities') plus a clear scenario (agent knows the goal but not which SML API serves it). It does not explicitly name siblings like discover_capabilities or compare_capabilities, so the agent must infer the boundary rather than being told 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?

'Call this when an agent knows the goal ... but not which SML API serves it' is a clear use condition, reinforced by two concrete examples. No explicit when-not or named alternative is provided, so routing against sibling discovery tools is left partly 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 readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description still adds real behavioral context: the server never synthesizes cluster-health or synchronization claims, and errors return a structured payload. It does not discuss caching or rate limits.

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 usage, then behavior; nearly every clause carries weight. The closing timeout example partly repeats the earlier 'before starting paid work' guidance, which keeps it short of 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 parameterless read tool with an output schema, the description covers purpose, trigger, read-only semantics, the no-synthesis guarantee, and error behavior. Nothing an agent needs to call it correctly is missing, and return values are already documented by 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is 100% with additionalProperties false, so no compensating detail is 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?

States a specific verb (read) and resource (the live SqueezeOS status endpoint), and the scope 'live status endpoint' distinguishes it from every sibling capability/quote/verify tool. An agent can identify the operation without opening the schema.

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

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

Gives a clear when-to-use condition ('quick health check of the API host before starting paid work') plus a concrete trigger ('check status first if paid calls start timing out'). It does not name an alternative sibling or state when not to use it, but no sibling overlaps this preflight role.

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 flag readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description goes well beyond them, disclosing the x402 USDC-on-Base payment challenge, that no payment is auto-spent, that a supplied signature authorizes one irreversible settlement, and that unavailable sections are labeled with a reason plus a coverage field. These are exactly the behavioral traits an agent must know before invoking a paid write-like call.

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?

Strongly front-loaded with the payload then the usage condition, and every clause is information-bearing. There is mild redundancy across the payment clauses ('never auto-spends,' 'nothing is charged,' 'an honest not-available result'), which keeps it from a perfect score, but the paragraph remains tight for the breadth of behavior it covers.

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, and the description instead supplies the pieces the schema cannot: payment flow, failure/not-available semantics, coverage labeling, and a use-case example. For a paid, non-idempotent, open-world tool this is complete enough to invoke correctly on the first attempt.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to payment_signature ('bound to this exact challenge', 'authorizes one paid, irreversible x402 settlement') that the schema's one-line description does not fully convey. The symbol parameter adds little beyond 'one US ticker,' which the schema already covers, so this stops short of 5.

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 ('Get a one-call intelligence profile for one US ticker') and enumerates the exact payload sections returned (quote, gamma regime, flow, squeeze score, FTD/Rex SHO, Oracle directive). It distinguishes itself from aggregation alternatives by framing the value as 'a full picture of a stock in a single paid call instead of stitching several sources together.' An agent can tell what this tool produces without opening the schema.

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

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

Explicit when-to-use is given ('Use this when an agent needs a full picture of a stock in a single paid call'), the alternative (stitching several sources) is named, and a concrete scenario ('profile GME before writing a research note') anchors usage. The payment path is also conditionally specified: unsigned call returns a challenge, retry only with a challenge-specific payment_signature.

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, but the description adds real context beyond them: that the doc is canonical and static, that spend terms are authoritative only in the target resource's fresh PAYMENT-REQUIRED challenge, and that errors return a structured error. It does not cover auth or rate limits, but the safety profile plus staleness caveat are well handled.

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

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

Front-loaded with the purpose, then usage, then behavioral caveats, so an agent can stop reading early. It loses a point for mild redundancy: the header-name example appears twice ('challenge and response header names' vs. 'the PAYMENT-SIGNATURE header name').

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 discovery tool with an output schema, the description covers everything needed to call it: purpose, timing, idempotency, error behavior, and the important caveat that the returned contract is not the authoritative spend terms. Nothing material is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. It correctly implies a parameter-free fetch ('read it once per session') without contradicting the empty 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 ('Read the canonical SqueezeOS x402 v2 discovery contract') and scopes it as a static protocol-rules document, which cleanly separates it from the diagnostics-flavored x402_readiness and x402_evidence siblings. An agent can tell what it gets back without opening the schema.

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

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

Gives clear timing guidance: use it when the agent needs payment protocol rules 'before attempting any paid call,' and 'once per session to learn the PAYMENT-SIGNATURE header name.' It lacks any explicit comparison to the several nearby x402_* siblings, so the 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the sentence 'Read-only and idempotent; no side effects' largely repeats structured data. What the description does add is domain behavior not in annotations: the rule that challenges/signatures are not settlement proof, and that errors return a structured error rather than failing opaquely.

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 usage, then behavior, then example – good ordering with each sentence doing work except 'Read-only and idempotent; no side effects,' which duplicates the annotations. Overall five sentences for a zero-parameter tool is slightly generous but not padded.

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 0 parameters and an output schema present, the description need not explain return values, and it correctly stays out of that. It covers purpose, selection criteria, safety profile, and error behavior, leaving no material gap for an agent deciding whether to call it.

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

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

The tool takes zero parameters, which sets a baseline of 4; there is nothing for the description to clarify or compensate for. The only parameter-adjacent content is the example use case, which is contextual rather than semantic.

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 specific verb+resource: 'Read real settlement evidence recorded by the canonical x402 rail,' and explicitly defines what does NOT qualify ('a challenge or signature alone is never treated as revenue or settlement proof'). This scope boundary clearly separates it from siblings like x402_contract, x402_readiness, and aftersearch_verify_serp.

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

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

It states a clear when-to-use: 'when an agent or auditor needs proof that a past payment actually settled in USDC on Base,' and gives a concrete scenario ('pull evidence for a disputed charge before deciding a refund'). It never names an alternative tool by name, so routing is implied rather than directive.

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=false, so the description's 'read-only and idempotent; no side effects' largely restates structured data. It does add that it is a live check and that errors return a structured error, which is genuinely additive, but the behavioral picture beyond annotations is thin.

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, then the trigger, then supporting detail, closing with a concrete example. Mostly waste-free, though the read-only/idempotent/no-side-effects clause is redundant with annotations and could be trimmed.

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 no input parameters, the description need not explain return values, and it covers purpose, timing, and error behavior. It is nearly complete; only the routing against the other x402 siblings 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add or omit. No syntax, defaults, or formats are 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?

States a specific verb and resource: check the live x402 payment-rail readiness surface, returning its readiness status. This is distinguishable from siblings like x402_contract and x402_evidence, though the description never names them to sharpen the boundary. Clear but not maximally differentiated.

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 a concrete trigger: 'Call this when an agent is about to attempt a paid call and wants to confirm the rail is up before building a payment signature,' reinforced by the batch example. Clear context, but no explicit exclusions or named alternative when the rail is down or when another x402 tool is the better fit.

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