ARYSPHERE x402 chain reads and token verdicts

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

Beyond readOnlyHint=true, the description discloses payment terms, the two-step no-payment then signed-payment retry flow, output limitations, grading rules, depth rules, and what is not covered. It is consistent with the read-only GET 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?

The definition is front-loaded with purpose, return behavior, pricing, and payment flow before the lengthy measured-output example. It is verbose and repeats disclaimers, but the length is justified by the nonstandard payment flow and absence of an output schema.

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

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

With no output schema and only readOnlyHint, the description supplies the missing behavioral and return details, including a full measured output example, grading methodology, market-depth rules, and payment mechanics. An agent has enough information to invoke and interpret the 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 description coverage is 100% and the single token parameter is documented in the schema as '0x + 40 hex'. The description reinforces that it operates on one token contract but adds no parameter-specific syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource: a Base ERC-20 token verdict with grade and on-chain facts for one token contract. The chain and scope distinguish it from the Ethereum-mainnet sibling token-verdict tools.

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

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

It gives clear usage context: one token contract, Base ERC-20, no holders or safety/legitimacy call, and an explicit x402 payment procedure. It does not explicitly name when to use the Ethereum-mainnet or preview siblings instead, so it falls short of full alternative 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 only declare readOnlyHint=true; the description goes well beyond that by disclosing the x402 price ($0.002 USDC), accepted payment chains, the two-step 402 challenge flow, the HTTP route, and the fact that everything is read from chain rather than computed by a model. It does not cover failure modes (bad proposal hash, unverified target, revert) which keeps it from a 5. No contradiction: reading chain state is consistent with readOnlyHint even though a payment is settled.

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 operative content is front-loaded in the first sentence and the payment mechanics are clearly separated, but the 'Returns:' sentence restates the opening nearly verbatim ('a DAO proposal preview on one OpenZeppelin Governor proposal') before adding the return list, which is avoidable duplication.

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 7 parameters, 6 required, no output schema and no destructive side effects, the description supplies everything an agent needs: what goes in (exact propose() arguments, sourced from ProposalCreated), what comes out (targets, state, votes, quorum, timelock, verification flags), and how to pay. Nothing material is left to inference.

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 already 100%, so the schema carries the baseline; the description adds real cross-field meaning the schema cannot express — that targets, values and calldatas must be the exact propose() arguments, that they hash to the proposal id, that the hash is checked on chain, and where to copy them from (ProposalCreated event). That is genuine semantic lift above the field-level descriptions.

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 first sentence names a specific verb-and-resource pair (preview of one OpenZeppelin Governor DAO proposal), scopes it to Ethereum or Base, and enumerates the exact payload: decoded targets, proposal state, votes, timelock delay. The line 'No verdict, no model' plus 'Check this first' cleanly separates it from the sibling dao_proposal_verdict.

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?

'Check this first' plus 'No verdict, no model' implicitly routes an agent needing an actual judgment to the verdict sibling, and the payment handshake instruction ('Call once with no payment... Retry the same call with the signed payment') tells the caller exactly how to sequence the two calls. What's missing is an explicit naming of the alternative tool under a stated condition, so it stops just 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 only declare readOnlyHint=true, yet the description adds substantial behavior: the verdict is derived from decoded targets, governance reads, Slither flags and a fork-simulation diff of outflows/mints/ownership changes; unverified contracts return UNKNOWN rather than being assumed clean; and the exact cost ($0.25 USDC, x402 on Base/Polygon/Arbitrum) plus payment handshake are disclosed. This is context an agent cannot get from the annotations alone.

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

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

Purpose is front-loaded and the labeled 'Returns:' segment is scannable. There is some redundancy — the opening line and the 'Returns:' line both restate 'GO, CAUTION or BLOCK on one OpenZeppelin Governor proposal' — and the payment/URL block is verbose, but each block carries necessary x402 information.

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

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

For a 7-parameter read-only analysis tool with no output schema, the description explains both the return (a graded verdict with its evidence sources and the UNKNOWN rule) and the payment protocol needed to actually obtain it. 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 coverage is 100%, so all seven parameters (chain enum, targets, values, calldatas, governor, descriptionHash) are already documented in the schema, including the propose()-argument/hashing semantics. The description adds only the chain scope at the parameter level, so baseline 3 applies.

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

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

States a specific verb and resource ('GO, CAUTION or BLOCK on one Governor proposal') plus the chain scope (Ethereum or Base), and distinguishes itself from the token-verdict siblings by naming OpenZeppelin Governor proposals as the subject. An agent can tell instantly this is the governance-proposal analyzer, not a token scanner.

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 operational guidance for the x402 flow: 'Call once with no payment. The result is the payment terms. Retry the same call with the signed payment at _meta["x402/payment"].' It also surfaces the cheaper preview endpoint as an alternative, but never states a when-to-use/when-not rule relative to the dao_proposal_preview sibling tool.

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?

Discloses price ($0.01 USDC), accepted payment chains, the two-step handshake failure mode, and the disclaimer that results are entertainment rather than advice. It also exposes the grading rule and pool-depth thresholds, so the agent knows these are deterministic rules over contract state, not a safety judgment. Consistent with readOnlyHint=true (a paid read, not a mutation).

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 and scope, followed by payment mechanics and return fields; nothing is buried. The embedded measured-output blob is long and repeats the disclaimer verbatim twice, but with no output schema it is the only channel conveying the return shape, so most of the length 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?

There is no output schema, and the description compensates fully: it enumerates the returned facts (code size, name, symbol, decimals, supply, owner(), proxy slots) and the market block (deepest Uniswap V3 pool price and depth), plus the grade enum and grading rule. An agent can predict the response and the payment failure mode before calling.

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 and schema coverage is 100% ('token contract, 0x + 40 hex'), so the schema carries the format burden. The description adds that the contract must be an Ethereum mainnet ERC-20 read for its own state, but adds no further argument semantics. Baseline 3 applies when the schema already documents the input.

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 verb+resource+scope: a rule-based grade plus on-chain facts for one Ethereum mainnet ERC-20 contract, with an explicit negative scope ('No holders, no safety or legitimacy call'). The chain qualifier implicitly separates it from base_token_verdict_v3, but the sibling eth_mainnet_token_verdict_preview is never mentioned, so the agent must infer which of the two mainnet tools to pick.

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 operational guidance for the x402 payment flow ('Call once with no payment. The result is the payment terms. Retry the same call with the signed payment at _meta["x402/payment"]'), which is non-obvious and essential. It also rules out what the tool will not answer. It does not, however, say when to use the _preview sibling or when a Base token should route elsewhere.

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?

Consistent with readOnlyHint=true and goes well beyond it: discloses the price ($0.002 USDC), accepted payment chains, the two-step unpaid-then-repaid handshake, and exactly which state is read from chain (code size, decimals, supply, owner(), proxy slots). It also explicitly bounds the behavior by listing what it does NOT do (no grade, no pool price, no holders, no safety 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?

Front-loads the purpose well in the first line, which is a strength. However, the exclusion list ('No grade, no model, no pool price, no holders, no safety or legitimacy call') is repeated verbatim in the description body and again inside the sample note field, and the full raw JSON blob bloats the text without adding much beyond what one example would.

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 embedded measured output usefully shows return shape, and the payment mechanics, scope, and exclusions are all covered. Minor gaps remain: no failure/error behavior (e.g., what happens if the address is not a contract or on the wrong chain), which the 'erc20_shaped'/'is_contract' fields hint at but the text never explains.

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 and the schema already documents it fully ('token contract, 0x + 40 hex' at 100% coverage), so baseline applies. The description adds only 'one token contract' plus a sample USDT address in the measured output; it offers no format, checksum, or non-ERC20 handling guidance beyond the schema.

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

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

States a concrete verb+resource: reading Ethereum mainnet contract facts (name, supply, owner, code) for a single token. It also names what the sibling eth_mainnet_token_verdict adds ('the contract facts the full verdict reads') and excludes Base by branding the chain, so the agent can distinguish it from the other verdict tools without opening a 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 explicit procedural guidance for the x402 flow: 'Call once with no payment. The result is the payment terms. Retry the same call with the signed payment at _meta["x402/payment"].' It implicitly frames when this is the right tool (facts only, no grade/model), but never says outright 'use eth_mainnet_token_verdict when you need a grade', so routing to the full-verdict sibling is left to inference.

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