finstack-mcp

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

With no annotations provided, the description carries the full burden. It successfully documents functional behavior (scanning Nifty 50 universe, threshold logic) and trading semantics (momentum vs value signals). However, it omits operational traits: it doesn't state whether the tool is read-only/safe, mentions rate limits, or describes the output structure despite having an output schema.

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?

Excellent structure: one-line purpose, trading rationale justification, Args documentation, and concrete examples. No wasted words; the 'most popular scan' claim establishes credibility, and the momentum/value distinction justifies the scan_type options. Information is front-loaded with the core function stated immediately.

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?

Given the simple 2-parameter schema and existence of an output schema, the description is largely complete. It successfully documents parameters that the schema omits. Minor gap: doesn't explicitly state the tool is non-destructive/read-only (critical given the 'scanner' name could theoretically imply writes) or data freshness details.

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 0% (properties lack descriptions), but the description fully compensates with an 'Args' section detailing valid values for 'scan_type' ('near_high', 'near_low', 'both') and semantics for 'threshold_pct' ('Closeness threshold in %'). The three invocation examples further clarify parameter usage patterns.

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 ('Scan') and clearly identifies the resource ('Nifty 50 stocks') and scope ('near their 52-week high or low'). It distinguishes from generic screeners by specifying the 52-week extreme focus and mentions it's a specialized scan from Screener.in, differentiating it from the sibling `stock_screener` tool.

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 clear contextual guidance on when to use each scan type: 'near_high' for momentum candidates versus 'near_low' for value opportunities or falling knives. However, it lacks explicit alternatives (e.g., 'use stock_screener for custom filters') or explicit 'when not to use' guidance.

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