Index Performance Ranking

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: the in-progress period is excluded ('Only COMPLETED periods are counted'), the data source is specified ('official NSE index closing levels'), and the return shape is disclosed (per-period plus cumulative, sorted). These are semantic nuances that materially affect result interpretation.

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?

Five sentences with the core purpose front-loaded in the first sentence, followed by output format, coverage scope, usage guidance, and the behavioral caveat in logical order. The sector enumeration is long but defensible as it documents the coverage claim (~140 indices). Every sentence earns its place, though the list could be tightened.

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-only ranking tool with six optional parameters and no output schema, the description covers everything an agent needs: what it computes, the output structure (compensating for the missing output schema), coverage scope, when to use it, and the completed-periods caveat. No critical operational gap remains.

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%, and the schema already explains all six parameters clearly, including the meaning of 'completed periods', the gainers/losers ordering, and the 'sectoral for sector rankings' guidance on category. The description reinforces these concepts but does not add meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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?

States a specific verb and resource ('Rank NSE indices by RETURN over recent completed weeks or months') with a defined output ('per-period % plus cumulative %, sorted best-to-worst'). The scope is unambiguous and the example queries ('rank sectoral indices by 3-week return', 'which sector performed best last month') make it easy for an agent to map user intents to this tool, distinguishing it from get_index_history (raw price history) and constituent-based estimation.

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?

Provides explicit positive guidance ('USE THIS for...') with concrete natural-language query examples, plus an explicit exclusion ('do NOT compute a sector return from its constituents, which is only an approximation'). While no sibling tool is named by name, the directive is specific and actionable, covering both when-to-use and when-not-to-use with clear conditions.

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