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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: deterministic execution, transient processing with no storage/logging/retention, browser delegation URL behavior, gpu:true delegation, and AP2 artifact export with execution_hash. This goes well beyond the annotations and gives the agent meaningful expectations about side effects and compute behavior. There is no contradiction.

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 packed with provenance and chain-integration details, and the first two sentences redundantly repeat that this is an OpenChainGraph compute node. Upstream/downstream artifact links and the FV-status receipt may be valuable environment context, but they dilute the invocation-critical information and push the description past what an agent needs for selection and use.

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?

Despite the rich annotations, output schema, and chain metadata, the core functionality — what the x402 header decoder, payload linter, and flow simulator actually compute — is never described. Policy parameter field names are deferred to a manifest, and no example or input shape is provided. An agent selecting between x402-related tools would not have enough functional grounding from this description 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 description coverage is 100%, so the schema already documents compute, parent_hashes, parent_tool_ids, and policy_parameters. The description mostly restates compute-mode behavior and operational constraints, adding no extra meaning for parent_hashes, parent_tool_ids, or policy_parameters. Policy parameters remain opaque and deferred to 'the tool's manifest', so the schema still carries the burden.

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 concrete noun phrases — 'x402 Header Decoder, Payload Linter & 402 Flow Simulator' — which convey the general function, and it identifies the tool as an OpenChainGraph compute node. However, it never explains what the decode/lint/simulate behavior actually does, so it is clear at a high level but does not meaningfully differentiate from related x402 tools such as decode_x402_payment or lint_x402_v2_migration.

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?

There is no guidance on when to invoke this tool versus alternatives, and no exclusions or alternative tool names are given. The description does provide compute-mode instructions and advises using synthetic or anonymised inputs, but that is operational detail rather than selection guidance between sibling tools. An agent must infer usage from the tool 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.