verify_receipt

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

Annotations already include readOnlyHint, idempotentHint, destructiveHint. Description adds details: auto-detects formats, offline operation, specific error strings (invalid_signature, no_public_key), and key resolution logic. 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?

Description is dense but each sentence adds value. Slightly verbose with full return JSON structure, but front-loaded with purpose. Could be slightly more concise without losing clarity.

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?

No output schema, but description fully specifies return JSON fields (valid, error, type, format, kid, issuer, hash) and error conditions. Covers edge cases like unparseable input. Complete for this tool's complexity.

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%, but description adds value by explaining precedence between artifact_json and path, and clarifying that public_key_hex is optional with fallback behavior. This goes beyond the schema 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 description explicitly states 'Verify the Ed25519 signature of a single signed artifact' and lists specific artifact types. It clearly distinguishes from siblings like verify_bundle and explain_artifact.

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?

Provides guidance on when to use artifact_json vs path, explains optional public_key_hex, and describes behavior when no key is available. However, it does not explicitly mention when to use alternatives like verify_bundle for multiple artifacts.

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