Smart money

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it is computed live from the current holder set, cached for about five minutes, and the 'verified' tag has a defined win-rate threshold. No contradiction 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 dense but efficient: definition, freshness, usage, exclusions, and cost all in a compact paragraph. The trailing 'Arguments: address and chain; one API unit on any chain' is slightly redundant with the schema, but every other sentence 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?

For a read-only, 2-parameter tool with full schema coverage and an output schema, the description is complete: it covers purpose, freshness, threshold logic, when to use when not to, and cost. Return-value details are delegated to the output schema, which is appropriate.

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 the baseline is 3; the schema already documents address format, chain enum, defaults, and validation rules. The description only names the arguments ('address and chain') and the API cost, adding no meaning beyond the schema.

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 opens with a precise definition: wallets with a track record of profitable entries that are holding or trading this token, classified from historical win rates. It also specifies the 'verified' threshold (50% win rate), which sharpens the concept beyond the tool name. It distinguishes itself from siblings by explicitly stating what it is not (risk assessment, wallet size).

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?

It gives an explicit use case: 'Use it for the bullish side of a scan: who informed is in, and when they got in.' It names the sibling for the excluded use case (get_whales for wallet size) and states that informed presence never offsets a rug signal, so an agent won't misuse it for risk decisions.

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