Settlement history and reputation gap

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

The readOnlyHint and openWorldHint annotations already cover the safety profile and that it queries external state. The description adds valuable context beyond that: it explains the source is the Algorand indexer, each item includes a counted flag, and that counted:false indicates earned but uncredited reputation. It also highlights that this requires reading both transfer logs and registry boxes, giving insight into the underlying computation.

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 two sentences, completely free of filler. The first sentence states what it does, the second explains the meaning of the key flag and why it matters. It is front-loaded and every phrase earns its place.

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 carries the burden of explaining what will be returned. It clearly states it lists transfers and each is marked with counted true/false, and interprets the counted:false case. It could have mentioned additional fields like amount, sender, or timestamp, but these are implied by 'USDC transfers'. For a listing tool, it provides sufficient context to understand the output shape and the purpose of the data.

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 description coverage is 100%, so each parameter (limit, address, agentId) already has useful descriptions in the schema. The tool description does not add extra parameter-level semantics, but it does clarify the concept of 'for an agent' which maps to agentId/address. Per calibration, baseline 3 is appropriate when the schema handles the heavy lifting.

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 lists real USDC transfers for an agent from the Algorand indexer, with a specific twist: each transfer is marked as counted or not by the ReputationRegistry. This distinguishes it from sibling tools like ripar_get_reputation (which presumably fetches current reputation) and ripar_list_jobs (which lists jobs), making it immediately clear what unique data this tool provides.

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: to see the reputation gap between actual transfers and what was credited. It explains the gap is only visible by reading the transfer log together with registry boxes, which tells the agent why this tool exists. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to choose it over siblings.

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