Automaton Colony

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

Adds rich context beyond annotations: the x402/USDC payment model, first-read latency up to 60s with an instruction to keep the connection open, safe retry semantics (same authorization never charged twice), the PaymentRequired response when unpaid or when payment fails with the x402 errorReason, and proof-of-read via block number and hash. Annotations cover readOnly/idempotent flags, but the description supplies the operational detail those flags cannot.

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

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

Dense and front-loaded with the most decision-relevant facts (payment, synchronous return, retry policy), and every sentence carries operational weight. It is on the longer side, but the length is justified by the payment and error-handling complexity.

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

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

For a paid tool with no output schema, the description still explains what comes back (the fact plus the block and block hash) and how failures surface (PaymentRequired document with isError and errorReason). Nothing an agent needs to invoke it correctly or interpret responses is missing.

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

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

Schema description coverage is 100%, so the enum values and targetAddress regex are already fully documented in the schema. The description only points to the catalog tool for the price list and does not add syntax or meaning beyond what the schema provides, which is the expected baseline.

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

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

States a specific verb and resource ('Buy one on-chain fact about a Base contract') and immediately distinguishes itself from the sibling buy_flash_audit by noting the answer returns in this call rather than requiring a poll. An agent can differentiate it from check_contract_free and buy_flash_audit 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?

Explicitly directs the agent to call contract_data_catalog first for the list and prices, and contrasts its synchronous behavior with buy_flash_audit. It also documents the retry condition (resend the SAME payment within 10 minutes) and the free-path fallback, leaving little 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?

Goes well beyond the annotations by disclosing the full payment lifecycle: async settlement, an orderKey returned for later collection, and the exact failure modes (wrong amount/recipient, insufficient balance, bad signature, expired or reused authorization). It explicitly reassures that a failed validation charges nothing, which is high-value context for a non-idempotent purchase tool.

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

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

Front-loaded with the payment mechanism and then the outcomes, with no filler sentences. The failure-mode sentence is dense and run-on, but every clause conveys a distinct behavior the 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 no output schema, the description still specifies both return shapes (PaymentRequired document vs orderKey) and the error envelope including where errorReason appears. For a complex, money-moving tool, nothing an agent needs to 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?

Schema description coverage is 100% and both parameters are fully documented in the schema (address pattern, language enum with default), so the schema carries the semantics. The description adds no parameter-level detail beyond the schema, which is the expected baseline when coverage is complete.

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 (buy a flash report), plus the payment rail (x402 in USDC on Base), so the agent knows exactly what this call does. It distinguishes itself from siblings by explicitly naming collect_flash_audit as the downstream step and describing the free web-store alternative.

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 context for when this tool applies: it must be paid via _meta["x402/payment"], and without a payment it returns the PaymentRequired document. It also routes the agent to collect_flash_audit for retrieval, though it does not explicitly contrast with the sibling buy_contract_data or state when to prefer a free check instead.

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

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

Annotations already 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.