stocks_get_gainers_and_losers

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

Annotations are absent, so the description carries full behavioral burden. It discloses the top-20 list limit but does not explain the return format, sorting criteria, time period, or whether any authorization is required. This minimal disclosure leaves critical behavioral aspects implicit.

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 extremely concise, using two short sentences that front-load the primary purpose and immediately detail the parameter. Every word adds value, with no redundancy or filler.

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 description adequately covers the basic action and parameter, but it omits details about the response structure, the time period considered for gainers/losers, and the selection criteria (e.g., percentage change vs. dollar change). Given there is no output schema, these details would materially improve completeness.

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?

The schema's direction parameter has no description or enum, and the description explicitly defines the allowed values ('gainers' or 'losers'). This adds essential meaning beyond the schema, making the parameter semantics clear for an agent.

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 clearly states the tool retrieves top 20 gainers or losers, with the direction parameter determining which list. The verb 'Get' plus resource 'top gainers/losers' is specific and unambiguous, and the tool name disambiguates from forex/crypto siblings.

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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is for stocks specifically, nor does it contrast with the forex and crypto versions of the same tool, leaving the agent without contextual usage cues.

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