rank_candidates

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

With no annotations provided, the description carries the full burden. It discloses concrete behavioral details: symbols with missing history appear under 'unavailable' rather than being silently dropped, each symbol costs a separate history request (rate/cost implication), and the tool returns specific metrics (trend, RSI, ATR, drawdown). This goes well beyond a generic read-only expectation, though it does not mention edge cases like invalid symbols or network errors.

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-structured: a one-sentence summary, a supporting paragraph on usage and outputs, a clear non-goal statement, and a compact Args section. Every sentence adds information; there is no fluff or repetition. The front-loading makes the core purpose immediately obvious.

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?

Despite having an output schema, the description enriches context by explaining the 'unavailable' behavior, the nature of the metrics, and the per-symbol cost. The tool has only three parameters and no nested objects, so the description covers the full decision-making surface. It is complete for both selection and invocation.

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 0%, so the description must explain all parameters, and it does so thoroughly. 'symbols' is described with a limit and per-symbol cost, 'benchmark' is explained as the relative-strength reference with default SPY, and 'lookback_days' is defined as calendar days of history. This adds meaning the raw schema lacks.

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 specific verb phrase 'Order a candidate list by relative strength', immediately distinguishing this as a ranking/screening tool compared to sibling data-retrieval tools. It further clarifies the output purpose ('shortlist worth spending the research agents on') and explicitly states what it does not do ('does not judge them').

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 phrase 'Turns a raw list into a shortlist worth spending the research agents on' provides clear context for when to use this tool (as a pre-research screening step). It also gives an explicit non-use ('does not judge them') to set expectations. However, it does not name alternative tools, so it stops short of a full 5.

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