Verify Evidence Bundle

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds significant behavioral context: it is free (no credits consumed), checks the bundle is owned by the API key, enumerates specific integrity checks, and discloses that it returns a signed action receipt. This goes well beyond the annotation hints and adds useful operational details.

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 well-structured with purpose, usage, return value, and examples. It is longer than minimal but each section earns its place. The Returns block may be redundant with the existing output schema, but it still aids quick comprehension without being overly verbose.

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?

The description covers when to use, alternatives, cost, ownership, what is verified, and receipt handling. Combined with rich annotations and an output schema, it leaves no major operational gaps for an agent to correctly select and invoke this tool. The context signals indicate high schema and annotation richness, and the description completes the picture.

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 for the single parameter bundle_id is 100%, including type, description, and an example. The description does not add parameter-specific semantics beyond the schema, so the baseline score of 3 is appropriate. The schema already carries the full burden for 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?

The description specifies a clear verb and resource: 'Verify the cryptographic integrity of an evidence bundle', and enumerates exact checks (manifest hash, EIP-191 signature, R2 artifact hashes). It also distinguishes itself from sibling bundle.get, which is for quick metadata lookups without full verification, making differentiation explicit.

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 explicit usage guidance: 'Use when you need to confirm a bundle has not been tampered with' and contrasts it with 'For quick metadata lookups (without full crypto verification), use bundle.get instead.' It also gives concrete example prompts that demonstrate when and how to invoke the tool.

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