Automaton Colony

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

The description discloses behaviors beyond the annotations: without a payment it returns a PaymentRequired error, with a valid payload it validates and settles asynchronously, and it returns an orderKey. The annotations only say readOnly=false and idempotent=false, so the description carries and richly satisfies the behavioral disclosure burden.

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

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

Two dense sentences deliver the payment prerequisite, the error path, the asynchronous settlement, and the follow-up collect step with no wasted words. Technical terms like x402 and PaymentPayload are packed in without padding.

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

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

For a paid asynchronous flow with no output schema, the description covers what an agent needs: how the transaction is paid, what happens on missing payment, what a successful call returns, and which sibling to call next. The remaining x402 mechanics are outside the tool schema and do not block invocation.

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

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

Schema coverage is 100%: targetAddress has format and chain details and language has an enum plus default. The description adds no parameter-specific meaning, which is acceptable because the schema already fully documents the parameters; 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 clearly frames the tool as a paid x402 purchase of a flash audit: it sends USDC on Base, validates a PaymentPayload, settles asynchronously, and returns an orderKey. It also distinguishes itself from the collect sibling by explicitly naming collect_flash_audit as the follow-up step.

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 clear context: use it when you have a payment x402 and want to buy a flash audit, and then use collect_flash_audit with the returned orderKey. It does not explicitly spell out when to prefer check_contract_free or flash_audit_terms, so the guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered there. The description adds meaningful behavioral context: no wallet needed, no verdict or score, observed on-chain facts only, rate limiting with a monthly quota. This goes beyond the annotations and sets correct expectations about limitations.

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

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

Two sentences with no filler. The most decision-relevant facts are front-loaded: 'Free, no wallet' and 'no verdict and no score'. The description then efficiently lists what the check covers and closes with practical rate-limit information. Every clause 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, no-output-schema tool, the description is complete enough for an agent to decide whether and how to call it. It explains the free/no-wallet nature, the output scope (facts, not verdicts), the main returned fact types, and the rate-limit constraint. No critical information appears 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 schema already covers the single parameter fully with a regex, a description of the expected address, and a network qualifier. The tool description reinforces that this is a Base address and mentions B20 native tokens, but it does not add significant semantic detail beyond the schema. With 100% schema description coverage, the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it performs a free check of a Base address/contract. It clearly scopes the tool to observed on-chain facts with no verdict and no score, and enumerates the fact categories (verified source, proxy detection, admin selectors, holder concentration, issuer powers). This strongly differentiates it from the flash-audit siblings, which imply paid, scored audit outcomes.

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

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

The description gives clear context for when this tool is appropriate: free, no wallet required, and useful for quick on-chain facts without a verdict/score. It also warns about rate limiting and monthly quota. It does not explicitly name alternatives or state when-not-to-use, but the context is strong enough to guide selection.

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?

Despite already having readOnlyHint, idempotentHint, and destructiveHint annotations, the description adds genuinely useful behavior: polling cadence, the DELIVERED state transition, and that the operation is free. This goes beyond what annotations alone communicate and does not contradict 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?

Two short sentences deliver the core behavior, the polling interval, and the cost model with no filler. The key information is front-loaded and every clause 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 polling tool with no output schema, the description tells an agent what to expect (status while settling, JSON when DELIVERED), how often to poll, and that it costs nothing. It does not enumerate possible intermediate statuses or a max polling horizon, but those are minor gaps given the simple shape.

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 provides only the orderKey parameter with a hex pattern and no description, so the description carries responsibility for explaining its meaning. It ties the parameter to 'an x402 order,' providing some resource context, but it does not explain where the key comes from or how it relates to the order lifecycle. This is adequate but thin.

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 behavior (poll/collect status) and a specific resource (x402 order), then clarifies the eventual output (report JSON once DELIVERED). This clearly distinguishes collect_flash_audit from sibling buy_flash_audit, which would be the order-creation counterpart.

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 strong usage context: this is a polling operation to be repeated every 10-15 seconds while the order settles and generates. It does not explicitly name alternatives or state when not to use it, but the lifecycle framing makes the intended use clear.

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, covering the safety profile. The description adds useful behavioral context beyond that: it returns a PaymentRequired document and is 'Free.' No contradiction with annotations exists.

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

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

One tight sentence front-loads the main purpose, lists the returned fields, and closes with 'Free.' Every word carries information; there is no filler or redundancy.

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 carries the burden of explaining return values, and it does so by naming the document type and its key fields. Terms like 'USDC base units' and 'request schema' could be slightly more explicit, but for a zero-parameter, read-only retrieval tool this is largely sufficient.

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

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

The tool has zero parameters and schema description coverage is 100%, so the baseline is 4. The description correctly avoids inventing parameter details, and there is nothing for it to compensate for 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 states a specific verb ('Returns') and a specific resource ('x402 v2 PaymentRequired document for the paid Flash Report'), and lists the exact contents (amount, network, asset, payTo, request schema). This clearly distinguishes it from sibling tools like buy_flash_audit and collect_flash_audit, which are about purchasing and collecting rather than retrieving 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 implies its role as a read-only way to obtain payment terms and notes 'Free,' but it never explicitly says when to use this tool versus siblings like buy_flash_audit, collect_flash_audit, or check_contract_free. No alternatives or exclusions are named, so an agent must infer its usage context from the resource name and sibling list.

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