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

Annotations already signal destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate mutation. It adds critical context: credit consumption, asynchronous completion, reuse behavior, concurrent handling, and what the receipt reports. It goes beyond the annotation by explaining that credit charge may not be complete and that identical initiations get retry guidance, which is valuable for an agent managing side effects.

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 dense and comprehensive, which is appropriate for a complex tool, but it could be tightened. It front-loads the core purpose and async behavior, then covers exclusions and plan details. Some redundancy exists (e.g., credit mentions appear multiple times), and the length might reduce scannability, but every sentence contributes to avoiding misuse.

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 tool's complexity (7 params, credit implications, async flow, plan variations), the description covers all critical aspects: what returns immediately, how to get results, reuse and concurrency, plan differences, and what it does not do. Combined with the detailed schema and output schema, an agent has enough to call it correctly. Minor gaps: it doesn't specify typical analysis_id format or timeout expectations, but these are less critical given the guidance to fetch results separately.

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 covers 100% of parameters with rich descriptions including enums, defaults, and alignment rules (e.g., risk_tolerance and analysis_emphasis). The description adds meaningful context beyond the schema: it clarifies that time_range is not a price forecast, that analysis_emphasis mismatches are rejected before credit consumption, and that evidence_history_family doesn't select a range on its own. These additions earn a 3, but since the schema already carries most of the semantic weight, 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?

The description clearly states the tool initiates a full StockLens AI analysis for a specific stock, with explicit scoping (single ticker) and immediate vs asynchronous behavior. It distinguishes itself from siblings by naming discover_stocks for multi-stock requests and fetch_analysis_result for retrieving results, so an agent knows exactly what this tool does and what it doesn't.

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 explicit when-to-use guidance (initiate analysis, retrieve results separately), when-not-to (does not screen, rank, compare, or trade), and names the alternative (discover_stocks for multi-stock, fetch_analysis_result for results). It also covers concurrency, credit consumption, and plan differences, leaving no ambiguity about selection.

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