search_stocks

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

With no annotations, the description carries the full burden. It reveals the data source (Yahoo Finance), query behavior (works best with partial tickers), a limit recommendation, and the fields returned. It does not disclose rate limits or error handling, but covers the key behavioral aspects for a search tool.

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?

Well-structured with a clear purpose, examples, a usage note, and an Args section. There is slight redundancy between the first two sentences ('Search for stocks' vs 'searches Yahoo Finance's database'), but the overall length is appropriate and content-rich.

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 is complete for a search tool: it explains parameters, usage, and return content. An output schema exists so return values are presumably defined, reducing the need for further detail. Minor gaps like error handling or case sensitivity do not significantly hinder an agent's ability to invoke the tool correctly.

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%, and the description compensates by explaining the query parameter (company name or ticker, with examples) and limit parameter (default 10, max recommended 25). This adds meaningful guidance beyond the bare schema definitions.

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 'Search for stocks by company name or ticker symbol' with a specific verb and resource. It distinguishes from sibling tools (get_stock_info, get_historical_data, etc.) by focusing on the search/discovery use case rather than retrieving specific data for a known symbol.

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 examples of effective queries and notes that complex multi-word queries may return fewer results, advising one company at a time. However, it does not directly compare with sibling tools or state when to prefer other tools over this search.

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