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

Annotations already cover the safety profile (readOnly, non-destructive), and the description layers on non-obvious behavior: results are capped, large results consume context needed later, null figures mean unknown, safety_tier grey is NOT a red flag while red is the only warning tier, and Moby refuses agent buys on red. It also disambiguates public market data from get_my_* wallet tools, which prevents a real class of misuse.

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 purpose and routing, and most sentences earn their place. It is dense, though, and the per-field whale block explanation partially duplicates what the output schema already defines, so a little length could be trimmed without losing routing value.

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 tool with a rich output schema, this covers everything an agent needs to call it correctly: id provenance, ordering, pagination cost, tier interpretation, and scope (market data vs. user data). No ambiguity remains about what the call will return or how to interpret edge values like grey tier and nulls.

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 only 60% and group_id has no schema description at all, but the description fully compensates: it names the source tool, gives literal example ids (home_majors, home_stocks, home_pulse, majors_solana), and forbids guessing. For whale_windows it adds the meaning of each returned whale field and clarifies whale_count is buyers-plus-sellers, not buyers alone — semantics the schema does not carry.

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?

Opens with a specific verb+resource: ranked tokens inside one group/category, best-first. It then explicitly separates itself from the closest siblings (get_screener_leaderboard, get_degen_leaderboard) and names the concrete group_ids that select the Majors/Stocks/Pulse variants, so an agent can route correctly without opening another schema.

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?

Gives explicit when-to-use routing across five boards, plus a hard precondition (group_id must come from get_screener_groups, never invented) and a negative instruction (never resolve a major or stock by ticker search, never keep your own mint list). It also states when not to paginate — only if the answer is genuinely not on page 1 — which is exactly the kind of usage guidance agents need.

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