Hash Anchor Data

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

The annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds meaningful behavioral details beyond them: the specific hash algorithm (blake2b-256), the return value format, and the mutual-exclusivity constraint on inputs. It does not cover error behavior or file-size limitations, but for a simple hashing utility that is a minor 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 front-loaded with the purpose, follows with concise argument descriptions, states the critical mutual-exclusivity constraint, and closes with the return value. Every sentence earns its place with no redundancy.

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?

For a read-only utility with no output schema, the description supplies the algorithm, the return value, the input options, and the exclusivity rule. An agent has everything needed to call the tool correctly without additional inference.

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 baseline is 3, but the description adds the important semantic rule that exactly one of the two path parameters must be supplied. That rule is not encoded in the input schema (both are optional with no oneOf), so the description meaningfully compensates.

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 states a specific verb ('Compute the hash'), a clear resource ('anchor data from a file'), and the exact algorithm ('blake2b-256'). It is unambiguous relative to all sibling tools, which cover querying, key generation, and certificate creation rather than anchor-data hashing.

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 a critical input constraint ('Exactly one of file_binary or file_text must be provided') but gives no guidance on when to use this tool versus any alternative. It does not mention prerequisites, context, or related workflows, leaving the agent to infer usage entirely from the name and parameters.

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