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

Goes well beyond the readOnly/idempotent annotations: discloses statelessness, a 32 KB size cap, 60 RPM rate limit, '?demo=true' and x402 (50 sats) payment paths, and HTTP 400 on invalid input. This is exactly the operational context annotations cannot carry.

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-loads purpose, then usage, then operational constraints; every sentence carries weight. Docked one point because the embedded default-window detail is both wrong and adds noise against the schema.

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?

Output schema covers return values and annotations cover safety, so the description only needs operational context — which it supplies (rate limit, size, payment, demo). The one gap is the ambiguous/conflicting window default that undercuts otherwise complete guidance.

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 baseline would be 3, but the description states window 'defaults to 1h' while the schema says it 'defaults to 24h when omitted' — an active contradiction that could cause wrong-window calls. The description adds no reliable meaning beyond the schema and instead introduces conflicting default info.

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?

States a specific verb and resource: tracks net accumulation/distribution flows across top Solana whale wallets and flags coordinated insider clusters for an SPL token. It explicitly distinguishes itself from the sibling evaluate_solana_token_risk, so an agent can tell them apart without opening schemas.

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?

Provides explicit when-to-use (analyzing on-chain smart-money order flow and holder clustering) and a named alternative for a different task (static mint/freeze authority checks → evaluate_solana_token_risk). The routing decision is clear.

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