Get an agent's reputation

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds crucial behavioral context: credits are keyed to payment IDs and the contract refuses duplicates but does not verify real transfers, so scores are claims not proofs. It also explains the 'never credited' vs 'scored zero' distinction, going well beyond the annotations.

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 paragraph but packs vital caveats and usage guidance without fluff. It could be split for readability, but every sentence contributes meaning, making it appropriately concise for the complexity.

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 fully describes what the read operation returns (payments credited, total USDC volume, validator verdicts), covers limitations (no real transfer verification), and explains edge cases (no score box). It provides all necessary context for an agent to invoke and interpret the tool correctly.

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 already provides 100% coverage for the single parameter with a clear description ('Registry id of the agent'). The tool description does not add further semantic detail about the parameter, so the baseline of 3 is appropriate since the schema carries the explanation.

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 uses a specific verb ('Read') and names the exact resource ('ReputationRegistry' app 768559198) and the data returned (payments, USDC volume, verdicts). It distinguishes itself from siblings by explicitly contrasting with ripar_settlements, making its purpose clear and unique.

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 explains when to use the tool ('Read an agent's score') and when not to trust it blindly, instructing the agent to call ripar_settlements to verify against the indexer before relying on the number. It also clarifies the meaning of a missing score box, giving clear guidance on interpreting results.

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