Automaton Colony

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds meaningful context beyond that: payment is required, results are returned synchronously, each result includes block and hash for verification, and missing payment yields a PaymentRequired document. It does not contradict annotations, but could additionally mention rate limits or precise 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?

Every sentence earns its place: pricing, synchronous behavior, verifiability, catalog prerequisite, and payment failure mode are all packed into a compact paragraph. The most important differentiator (unlike buy_flash_audit) is front-loaded, and no redundant filler exists.

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

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

With no output schema, the description reasonably explains what the response will look like (result with block and hash, or PaymentRequired document). It also covers prerequisites and free alternatives. Some ambiguity remains about the exact structure of the returned fact and how to interpret the free options, but the description is solid for a paid tool with a catalog companion.

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 well-documented in the schema (product enum and targetAddress pattern/conditional requirement). The description adds only minor semantic value by pointing to the catalog for prices and product details, and by clarifying that payment is passed via _meta rather than as a schema parameter. This meets the baseline but does not greatly exceed it.

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

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

The description states a specific verb-resource pair ('buy one on-chain fact about a Base contract') and immediately differentiates itself from buy_flash_audit by highlighting the synchronous response model. An agent can clearly determine this tool purchases a discrete fact rather than launching an async audit.

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 explicitly says to call contract_data_catalog first for product list and pricing, and contrasts with buy_flash_audit by noting there is no order to poll. It also mentions the payment prerequisite through _meta['x402/payment'], giving clear when-to-use and prerequisite 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?

Beyond the annotations, the description discloses the payment-gated behavior, the exact no-payment branch returning a PaymentRequired/isError document, asynchronous settlement, and the final orderKey result. This gives the agent a clear model of the tool's side effects for an open-world, paid operation.

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

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

Three sentences with no wasted words. The purpose and payment mechanism are front-loaded, and the error and success paths are presented in a clean if-then structure.

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

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

For a tool with no output schema, the description covers the key outcomes, PaymentRequired vs orderKey, and points to the next tool in the workflow. It does not state the exact price/amount or enumerate all error cases, but the core invocation and settlement flow are sufficiently complete.

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 schema already documents targetAddress and language at 100%, so the baseline is satisfied. The description adds crucial invocation context by naming the _meta['x402/payment'] field and explaining the PaymentPayload requirement, which is not visible in the input schema.

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

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

The description opens with 'Paid over x402 in USDC on Base', identifying the action (buy), the artifact (Flash Report), and the payment channel. It also separates buying from collecting by returning an orderKey to use with collect_flash_audit, making the purpose 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 description gives clear operational context: payment is required, absence of payment yields a PaymentRequired response, valid payment leads to async settlement and an orderKey, and wallet-less users are routed to the web store. It does not explicitly differentiate from siblings like buy_contract_data or check_contract_free, so it lacks a fully explicit when-not-to-use statement.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by adding operational constraints: rate limiting, a monthly quota, free usage, no wallet requirement, and the lack of a verdict/score in the output. This is valuable behavioral context not present in 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 sentences with no filler: the first sentence front-loads the free/no-wallet value proposition, the second lists the fact categories, and the third covers the operational constraint. Every sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description is quite complete: it explains what the tool returns (fact categories), the scope (Base addresses and B20 tokens), and key constraints (rate limit, monthly quota, free, no wallet). The only minor gap is the lack of any detail about the response format, but the fact list largely compensates.

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

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

Schema coverage is 100%, and the schema already fully describes the address parameter including its pattern and mainnet scope. The description's mention of 'Base address' and 'B20 native tokens' adds no new semantic meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states a specific verb ('check') and resource ('Base address'), then enumerates the exact categories of observed on-chain facts it returns: verified source, proxy detection, admin selectors, holder concentration, and B20 issuer powers. It also distinguishes itself from the flash-audit siblings by explicitly saying 'no verdict and no score'.

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

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

The description provides clear context for when to use the tool: when you need free, no-wallet, fact-only observations on a Base address. The phrase 'no verdict and no score' implicitly signals that for verdicts or scores one should use a different tool, but it never explicitly names the sibling flash-audit tools or states when to prefer them.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it returns status while settling, switches to the report JSON after DELIVERED, and is free. This goes beyond the annotations without contradicting them.

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 only three short phrases, each adding value: behavior during settlement, the delivered result, and polling cadence. It is front-loaded with the core purpose and contains 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 simple polling tool with one parameter, no output schema, and strong safety annotations, the description covers the key behavior and timing. It could be slightly more complete by noting that orderKey comes from buy_flash_audit, but it is not critically incomplete.

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 schema has 0% description coverage for the only parameter, orderKey. The description mentions 'an x402 order' but never explains where orderKey comes from, how it is validated, or how to obtain it, leaving the agent to infer the parameter meaning from the pattern alone.

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

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

The description clearly states the tool returns the status of an x402 order and, once DELIVERED, the report JSON itself. This is a specific, actionable description that distinguishes it from siblings like buy_flash_audit and check_contract_free.

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 explicitly instructs the agent to poll every 10-15 seconds and implies use while an order is settling. It does not explicitly name alternatives or state when not to use the tool, but the polling guidance is clear and useful.

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 mark the tool as read-only, idempotent, and non-destructive; the description adds meaningful behavioral context beyond that by stating it is free, requires no wallet, lists prices in USDC, and explains answer validity. It does not disclose return formatting, but the safety and cost behavior are well 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?

The description is three sentences with no wasted words. The most important information ('Free, no wallet') is front-loaded, followed by the tool's core function and a practical recommendation.

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

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

Given zero parameters, a simple catalog purpose, and annotations that already establish safety, the description covers everything an agent needs to invoke and interpret the tool correctly. The pricing, validity, and pre-purchase guidance round out the intended use.

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 schema description coverage is 100%, so there is no parameter ambiguity to resolve. The baseline of 4 applies because there are no inputs to explain.

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 ('Lists') and resource ('individual on-chain facts about a Base contract'), and clearly frames the tool as a free catalog with price and validity information. It is unmistakably distinct from the sibling buying tools such as buy_contract_data and buy_flash_audit, and from flash_audit_terms.

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 explicit placement: 'Read this before paying', making it clear this is a pre-purchase reference rather than a purchase action. It does not name sibling alternatives explicitly or state when not to use it, but the context strongly implies the intended 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=true, idempotentHint=true, and destructiveHint=false; the description does not contradict these. It adds useful behavioral context such as 'Free' and that the response includes guidance for people without a wallet, which is beyond what annotations and schema 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?

Two compact sentences place the primary return value first, then the exceptional no-wallet buying path. Every clause adds distinct information with no filler or repetition.

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

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

With no output schema, the description enumerates the response contents (amount in USDC base units, network, asset, payTo, request schema) and the additional web-store instruction, which is enough for a zero-parameter tool to be invoked correctly. Annotations cover safety and idempotency, so nothing essential 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 schema coverage is 100%, so there is no parameter information the description needs to compensate for. The description appropriately focuses on what the response will contain instead of parameters.

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

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

Description opens with a specific verb and resource: 'Returns the x402 v2 PaymentRequired document for the paid Flash Report'. It enumerates the meaningful fields (amount, network, asset, payTo, request schema), and the focus on payment terms clearly separates it from sibling tools like buy_flash_audit or contract_data_catalog.

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 makes the tool's context clear: this is the no-payment-needed lookup of payment requirements, and it even covers the walletless web-store path. It does not explicitly name alternative tools or state when not to use it, but the intended use case is evident from the subject matter.

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