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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value beyond these by specifying the endpoint, the exact data structure, and the crucial test-environment caveat (mock ledger, tUSDC, no real funds). It also discloses that the reputation measures specific aspects and not others, and mentions the optional self-asserted owner claim. No contradictions with 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, information-dense sentence that front-loads the core purpose ('Outcome reputation for a wallet') and then packs in the response fields, caveats, and test-money warning. It is efficient with no fluff, though it could be split into two sentences for readability. Every phrase adds value.

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 one-parameter, read-only tool with annotations covering safety, the description is quite complete. It enumerates the returned fields, clarifies scope ('what it measures and does not'), and flags the test environment. With no output schema, this is the sole source of behavioral info, and it provides enough for an agent to decide whether to call it and interpret the result.

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 description covers the parameter completely ('Wallet address (0x...)'), so the baseline is 3. The tool description does not add additional parameter-specific guidance beyond restating that it's for a wallet and giving the endpoint. Since schema coverage is 100%, the description's minimal extra input on parameters is acceptable.

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 states the tool retrieves 'outcome reputation for a wallet', names the endpoint (GET /v1/agents/{address}), and lists the exact fields returned (as_provider / as_buyer with sub-fields). It also distinguishes what it does and does not measure, which sets it apart from any potential siblings (none of which are reputation-related). The verb 'get' and resource 'reputation' are explicit and unambiguous.

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 clear context that this is a read-only reputation lookup and explicitly warns 'TEST MONEY ONLY: mock ledger, test tokens (tUSDC), no real funds', which is essential usage context. It also says 'what it measures and does not', helping an agent decide if it fits the need. However, it does not explicitly name any alternative tools or state when not to use it, though the lack of siblings for reputation makes this less critical.

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