byte_verify_payload

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

The description discloses the cryptographic verification process: 'Recomputes keccak256... compares to on-chain hash.' It explicitly states 'Read-only; no wallet or payment required,' aligning with annotations (readOnlyHint=true, destructiveHint=false). It also warns about consequences of failed verification, adding valuable context beyond 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 concise with 4 sentences, all front-loaded with purpose. Every sentence adds value: purpose, mechanism, mandatory usage instruction, and anchoring options. No wasted words.

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 the tool's simplicity (verification with a boolean result), the description fully covers what the tool does, when to use it, how it works, and the meaning of outputs (verified=true/false). The presence of output schema further reduces the need for return value explanation.

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?

Input schema covers 100% of parameters with descriptions. The description adds context: 'data' is the exact received payload, 'expectedHash' is the on-chain payloadHash, 'txHash' recovers the signer, and 'hashMode' explains hashing strategies. This enriches the schema definitions, though the schema alone is already informative.

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's purpose: 'Verify-before-act: confirm a data payload matches on-chain attestation.' It uses specific verbs (verify, confirm) and resource (data payload, on-chain hash), and distinguishes itself from siblings as a mandatory verification step before acting on BYTE-sourced data.

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 instructs when to use: 'ALWAYS call this on BYTE-sourced data before acting on it' and when not: 'if verified=false the bytes were tampered and MUST NOT be used.' It also provides options for anchoring with expectedHash or txHash, referencing sibling tools. It could improve by explicitly stating when not to use (e.g., non-BYTE data), but overall it's clear.

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