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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond these by specifying concrete behaviors: an unmeasured endpoint returns NOT_MEASURED with an empty list, never an error and never a clean bill; there is no verdict, score, or ranking; and the shard key is a sha256 of the normalized URL. This materially enriches the safety and expectation profile.

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 dense but logically organized: core purpose first, then capsule contents, retrieval mechanics, empty-result semantics, and a closing non-endorsement caveat. Every clause carries substantive value, though the length and technical density could be hard to parse at a glance for a simpler agent.

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?

With one simple parameter, a rich output schema, and annotations covering safety and world-openness, the description supplies all remaining decision-relevant context: empty-list vs NOT_MEASURED behavior, the inclusion verification pointer, and the per-batch origin of capsules. Nothing critical is missing.

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 documents endpoint_url with a clear example, and coverage is 100%. The description adds meaningful usage context—normalization via sha256 and single-endpoint scoping—which helps the agent understand how the parameter drives the lookup, even though the format is already well-specified.

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 reading operation: 'every published measurement capsule about ONE endpoint URL across all batches' and 'Read from a static per-endpoint shard'. It clearly differentiates this tool from aggregate-focused siblings like board_totals and from verification-only tools like verify_capsule, so an agent can tell what unique value this tool provides without opening schemas.

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 opening 'Trust per server, not totals' signals when to prefer this over aggregate views, and the mention of verify_capsule re-deriving inclusion points to the verification alternative. It does not explicitly list when-not-to-use or name an exclusion, but the context is clear enough for an agent to choose sensibly.

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