search_symbols

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe, non-mutating behavior is covered. The description adds that this tool 'Discovers exact symbol identifiers' and searches by name/ticker/description, but doesn't elaborate on output shape, rate limits, or search behavior beyond that. This is adequate baseline transparency given the annotations, but not exhaustive.

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 three short, front-loaded sentences. The first states the primary action, the second mentions result types, and the third gives usage context. No wasted words exist, though the second sentence is slightly redundant with the asset_type enum. Overall, it's concise and readable.

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 covers the essential use case, references asset types, and tells the user to use it before screening. With an output schema available, the absence of a return-value description is acceptable. The only gap is the failure to differentiate from the similarly named sibling 'lookup_symbols', leaving some ambiguity for an AI agent in edge cases.

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 100% and all parameters already have descriptions in the input schema (query, limit, start, exchange, asset_type). The tool description reinforces the concept of searching by name/ticker/description, but adds no new parameter semantics. Thus it meets the baseline for schema-heavy behavior but doesn't go beyond it.

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 a specific verb and resource: 'Search for TradingView symbols by name, ticker, or description.' It also frames the purpose relative to screening ('Use this before screening'), which distinguishes it from screen_* siblings. However, it does not differentiate it from the closely named sibling 'lookup_symbols', so it doesn't fully meet the strict 5 criterion.

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 gives explicit context for when to use this tool: 'Use this before screening when you need to find the correct symbol format.' This clearly signals a discovery/disambiguation role before other operations. It does not explicitly mention alternatives like lookup_symbols, so it lacks the when-not/alternative clarity of a top-tier guideline.

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