List Traders

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

The annotations already mark the call readOnly and non-destructive, and the description adds substantial behavior beyond that: it discloses the pagination schema, the empty-result behavior (traders == [] when registry is not built), and the max_hits filtering semantics. No annotation contradiction exists.

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 compact yet dense: purpose, row shape, return shape, edge case, pagination, workflow, and example are each one short clause or sentence. Nothing is filler, and the most important identifying information appears first.

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 simple paginated list tool with no required parameters and an output schema available, the description covers all essentials: what is listed, the filter, row fields, return fields, empty-registry fallback, pagination rule, example call, and follow-up usage. There is no significant missing context for an agent to call it 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?

With 0% schema_description coverage, the description fully compensates: it explains max_hits as filtering out high-frequency validator committers, offset via the pagination instruction, and limit via the example list_traders(limit=10, max_its=100). It also clarifies the returned counter fields total, count, if_set, has_more, next_offset, so parameter roles are inferable.

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 a specific verb and resource: 'Recently active trader addresses from the block-scanner registry' plus the filtering rule for max_hits. It also names related next-step tools (trader_profile / trader_pnl_stats), but it does not explicitly differentiate this tool from siblings like discover_traders or leaderboard, so it is clear but not fully sibling-distinguished.

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 gives a concrete workflow: list active traders, then feed an address into trader_profile / trader_pnl_stats. It also provides operational usage guidance such as 'Page with offset when has_more is true' and notes when the registry is unavailable. It omits explicit 'use this instead of X' guidance, but the intended context is clear.

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