Market Screener

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

Annotations declare readOnlyHint=true, and the description does not contradict it. It adds context beyond the annotation: mentions bulk data usage, cheap on quota, and the ability to fetch catalog with screen_type='list'. This is helpful for understanding performance and side effects. It doesn't describe pagination or return volume, but the added quota/bulk detail is valuable.

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 organized with bullet points and sections, front-loading the primary purpose. It includes a comprehensive list of screen types that is essential for correctness. While somewhat lengthy, each bullet earns its place. The structure is clear, though it could be trimmed slightly without losing value.

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 tool is complex with many screen types, and there is no output schema. The description ends with a generic 'Returns: Stocks matching the screen criteria' without detailing fields, result limits, or how to interpret the data. Given the variety of screens, more specifics on return format would be helpful. It doesn't mention error scenarios or quota limits beyond 'cheap on quota'. Overall, it's adequate but leaves room for clarification.

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 coverage is 0%, the description contains an 'Args' section that details each parameter (e.g., screen_type list, min_market_cap default $1B, exclude_earnings_days semantics). This fully compensates for the empty schema descriptions and even clarifies defaults. Parameter meanings are explicit and actionable.

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 it screens the market for trading opportunities and enumerates specific screen types (e.g., high_iv_rank, unusual_volume, pin_risk). It distinguishes itself from siblings like scan_volatility_arb and scan_relative_value by focusing on preset multidirectional screens across the full universe. The verb 'screen' + resource 'market' is specific.

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 an explicit 'Use this tool when' section listing user intents such as finding trading opportunities, screening high IV stocks, unusual activity scans, and what to trade. While it doesn't name alternatives or when not to use it, the context is clear enough for typical queries. It misses explicit exclusions but is still directive.

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