search_features

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical behavioral traits: catalog size (~1300+ assets), the limit ceiling of 2000, that a single call with limit=1500 suffices for large portfolio requests, and that no pagination is needed. It also explains the reliability advantage of category-based browsing over keyword matching, which is a non-obvious behavioral nuance not captured by annotations.

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 front-loaded with the core purpose, then organized into clear numbered usage shapes followed by preferential and cautionary guidance. Every sentence earns its place, offering practical examples and explicit caveats. Despite being longer than average, it is tightly structured and free of redundancy, making it efficient for an agent to parse.

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 moderate complexity (4 optional params, no enums) and the existence of an output schema, the description is remarkably complete. It covers all major use cases, explains catalog scope and limits, provides alternative-tool guidance, and addresses edge cases like large portfolio enumeration. The presence of an output schema means return-value details need not be restated, and the description fills every other contextual gap.

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?

Although schema descriptions cover all parameters, the tool description adds substantial semantic value by explaining how parameters combine. It demonstrates the three shapes with examples (query only, category only, query+category+is_asset), clarifies that query can be omitted for category browsing, and spells out the limit ceiling and default behavior. This goes far beyond the schema's per-parameter descriptions.

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 clear, specific verb+resource: 'Find tickers and market indicators in the catalog.' It then outlines three distinct usage shapes with concrete examples, making the tool's scope and capabilities unambiguous. It also explicitly differentiates from the sibling tool screen_universe, stating that search_features should not be used for full-catalog enumeration where screen_universe would be insufficient.

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?

Usage guidance is explicit and actionable. It states 'PREFER browsing by category to keyword-spam' and provides a concrete example where one category call replaces multiple keyword searches. It also gives a clear when-not scenario: 'Do NOT reach for screen_universe to enumerate the catalog' and explains why screen_universe is unsuitable, positioning search_features as the alternative for full-catalog enumeration.

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