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

Annotations already declare readOnly and closed-world, so the description does not need to argue safety. It adds genuine behavioral context beyond that: the computation is deterministic and formula-documented at /trust, and the return surface (confidence, flags, per-agent counts) is disclosed. It stops short of stating determinism caveats such as staleness or ledger-dependent latency.

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 body is a single run-on sentence with a long parenthetical catalog of fields and unexplained terms like 'honest retirements' and 'unhandled decays'. The most actionable instruction (omit agent for the ranked table) is stranded at the very end instead of being front-loaded.

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 no output schema, the description responsibly enumerates the returned metrics, and it covers both call modes. What is missing is any hint about ordering, pagination, or size of the ranked table, which matters for a table-returning tool.

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 0% — the single 'agent' string is undocumented — so the description must carry the meaning, and it does: supplying agent scopes to one agent, omitting it returns the ranked table. That is the essential semantic distinction for this tool, though the expected format of the identifier itself is never 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 names a specific resource (deterministic reputation from the public ledger) and enumerates the outputs (0-100 score with confidence, verified/refutation rates, flags, counters). It is clearly distinct from siblings like audit_ledger or get_reliance_prior, though the purpose statement is buried under metric jargon rather than stated up front.

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?

One explicit usage rule is given: omit agent to get the ranked table, which tells the agent how to switch between single-agent and table modes. There is no guidance on when to prefer this over audit_ledger, get_reliance_prior, or get_status, so the sibling routing is left to inference.

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