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

With no annotations provided, the description carries the burden of disclosing behavior. It reveals that the output is JSON containing hashes and verdict, and that oracles are excluded, which is useful context for a read operation. It does not mention potential error conditions, permission requirements, or whether the read is purely local.

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 a single succinct sentence that front-loads the core action and resource, then adds a clarifying scope qualifier. There is no wasted wording.

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 single-parameter read tool, the description covers the basic purpose and even hints at the output content. Still, it is missing guidance on card_id format, behavior when the card does not exist, and clearer differentiation from close siblings like verify_card.

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 schema has 0% description coverage for card_id, and the description does not compensate by explaining what a card_id is, its expected format, or how it maps to the card being read. The phrase 'one card' only weakly reiterates the singular nature implied by the parameter.

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 names a specific verb and resource: reading one sia-* card JSON. The parenthetical 'hashes and verdict, not oracles' adds useful scope and distinguishes the card content from oracle-style data, though it does not explicitly compare with sibling tools like read_suite or verify_card.

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 implies when to use this tool—when you need a single card's hashes and verdict—and 'not oracles' gives a mild exclusion. However, it provides no explicit guidance about when to prefer a sibling tool such as verify_card or read_suite.

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