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

Annotations already mark this as read-only, idempotent, and non-destructive, so the description needs less safety disclosure. The description adds valuable behavioral details: the per-category counting toward the daily API limit, omission of atr_pct when underlying data is missing/corrupted, and the precomputed Pro-tier AI messages with no extra AI cost. It clearly states what is returned and notes absent data. This is a good example of adding context beyond the schema. Minor lack: no explicit note about rate limits beyond the daily call counting, but most relevant behavior is transparent.

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 well-organized: a scope line, a pagination/limit note, a filter note, return fields, and a Pro tier explanation and pointer to a sibling. It is a little long, and the Pro tier narration ('A big mover's...' uses colorful language) adds length but also explanatory value. It front-loads the core purpose immediately and presents parameters in the same order as the schema. The slight extra length and marketing tone prevent a perfect 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?

The tool has a rich output schema and a clear list of returned per-stock fields, so the description doesn't need to repeat the full return shape. The input schema covers all three parameters with 100% coverage. The description covers the daily-limit accounting, the Pro-tier optional fields, and the alternative for full research; there is no major gap an agent needs to guess. For a list/read tool of moderate complexity, this is complete.

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 each parameter already has a rich description in the schema. The tool description adds the default for category and limit, the valid enum values, and a concrete example for min_market_cap_b. It also adds the critical interpretation that a symbol appearing in multiple categories counts once per category toward the daily limit, which clarifies exactly how limit/quota accounting works. This is a strong baseline 3 with meaningful added value, so a 4 is justified.

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 verb and resource: 'Top market movers from the Stocklake universe — gainers, losers, most active.' It clearly identifies the tool's function as listing market movers, and explicitly differentiates its output categories. The context that it returns a per-stock summary and points to the sibling get_stock_research for deeper research further distinguishes it from other tools.

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 states when to use the tool: it provides top movers and notes that Pro tier adds predefined AI narratives. It explicitly names the alternative get_stock_research(symbol) for full research on a single mover. It also gives selection guidance by showing the category and limit parameters. It does not explicitly mention when not to use it, but the guidance is strong overall.

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