disclosure_verify_artifact_hash

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

The description explains the computation and comparison logic, and details the return format on mismatch. However, it does not explicitly state that the tool is non-destructive or clarify any authorization needs, rate limits, or side effects. Given the lack of annotations, this is a moderate gap.

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 two sentences, front-loaded with the main purpose, and every sentence adds value. No redundant or ambiguous wording; it is efficient and well-structured.

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 the core functionality and parameter usage, but it fails to explain the required parameter document_json, which is only described in the schema. Without a clear description of what document_json is, the tool's completeness is diminished. Additionally, no output schema is provided, though the description partially covers return structure.

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?

The description adds meaningful context beyond the schema, such as specifying that candidate_text uses canonical SHA-256 with LF and no trailing newline, and that candidate_bytes_base64 is for binaries like PDFs/images. This compensates for missing schema descriptions on some 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 clearly states it recomputes SHA-256 and compares to a stored hash, specifying two modes for text and binary artifacts. However, it does not distinguish itself from sibling tools like disclosure_verify_prompt_hash or ai_evidence_verify_hash, which might have similar purposes.

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 clear guidance on which parameter to use based on artifact type (candidate_text for text, candidate_bytes_base64 for binary) and explains the canonical text mode. It does not explicitly state when not to use the tool or mention alternatives, but the context is sufficient for basic decision-making.

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