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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. With no output schema, the description usefully fills that gap by describing the returned content in both modes, and adds a real data caveat ('Traders appear by public username when they set one'), though it omits result limits/pagination and any cost or rate considerations.

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?

Front-loaded with the usage trigger, then the return contract, then the wallet handoff to pm_portfolio — a sensible order with no filler sentences. The trigger enumeration is long and slightly redundant ('who is buying or selling' / 'where the money is going'), which keeps it from a 5.

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 4 optional parameters, full schema coverage, no output schema and rich annotations, the description is nearly complete: it explains both invocation modes, the fields returned in each, and where to go next. Only secondary details (result caps, sorting of the largest trades, time-window interaction with min_usd) are left unstated.

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 coverage is 100%, so the baseline is 3, but the description adds a genuinely non-obvious conditional that the schema does not encode: min_usd applies only 'without a market', and the no-market mode is what produces cross-Polymarket whale trades. It also confirms market accepts a link or slug, matching 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 concretely enumerates what the tool produces (dollars traded and net direction per outcome, distinct wallets, largest trades, top movers, biggest holders) and states the two modes (with vs. without a market), which is far more than a restated title. It names one sibling (pm_portfolio) as a follow-up, but never distinguishes itself from pm_moves or pm_leaderboard, whose scopes ('why its price moved', leaderboard-style rankings) appear to overlap.

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 opens with an explicit trigger list ('Use this when the user asks who is buying or selling... why its price moved... what the whales are doing'), which is genuine when-to-use guidance, and it routes wallet-level depth to pm_portfolio. However, it gives no when-NOT-to-use exclusions and does not tell the agent how to choose between this and pm_moves/pm_leaderboard when the question is ambiguous.

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