get_movers

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds essentially nothing behavioral beyond that: it does not say how many movers are returned, whether results are paginated, or any rate/latency characteristics. The sorting detail it does provide is already available in the schema enum.

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?

A single efficient sentence with the core scoping information front-loaded and no filler. It is appropriately sized for the tool, though it could have used one more clause for usage guidance without becoming bloated.

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?

An output schema exists, so return formatting need not be described. Still, for a tool where every parameter is optional and behavior depends heavily on defaults (sort=PERCENT_CHANGE_UP, index=$SPX), the description omits the defaults and any guidance on selection, leaving the agent to read the schema to use it sensibly.

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 only 33% (only 'frequency' is documented in the schema), so the description must compensate. It partially does: 'sorted by volume, trades or % change' maps onto the sort enum values and 'index or exchange' hints at the index parameter. However, it does not explain that PERCENT_CHANGE_UP/DOWN are separate ranking directions, nor what INDEX_ALL/EQUITY_ALL/OPTION_* select.

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 states a specific verb-less but clear operation: 'Top movers in an index or exchange, sorted by volume, trades or % change.' It identifies the resource (market movers) and the ranking dimension, which no sibling tool (get_quotes, get_price_history, search_instruments) provides. It stops short of explicitly distinguishing itself from siblings, but the purpose is unambiguous.

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?

There is no indication of when to use this tool versus alternatives such as get_quotes or get_price_history, and no mention that all three parameters are optional or that defaults apply. Usage must be inferred entirely from the one-line purpose statement.

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