screen_stocks

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

Annotations are absent, so the description carries the full behavioral burden. It explains the filters format extensively, including an example, the '_l' suffix meaning, and that columns exclude null values. However, it does not disclose how results are ordered by default, what happens if filters are omitted, or the exact output structure (though an output schema exists). These gaps mean it's adequate but not comprehensive.

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 well-structured: a one-line summary, a detailed explanation of the filters parameter with an example, then a clean parameter list. Every sentence has purpose; no fluff or redundant statements. It's slightly long but appropriate for a tool with 9 parameters and complex filtering syntax.

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?

This is a complex tool with 9 parameters, a filter syntax, and cross-references to two sibling tools. The description covers the essential usage: filter format, parameter meanings, and routing to helper tools. With an output schema present, not describing return values is acceptable. Some edge cases (e.g., empty filters) are not covered, but overall the information is sufficient for correct invocation.

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 description coverage is 0%, so the description must compensate. It does so well: each parameter is explained with examples or allowed values (e.g., market: CN/HK/US, exchange: sh_sz/sh/sz/bj). The order_by field lists common metrics. This significantly clarifies the schema, which otherwise provides only names and types. Minor missing details like precise limit bounds are already in the schema defaults.

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 starts with '选股器' (stock screener) and clearly states it filters and sorts stocks by valuation, financial, and market indicators. This is a specific verb (screen/sort) and resource (stocks), and it differentiates from siblings like get_quote, get_kline, and search_stock which target individual stocks or quotes. The purpose is unambiguous.

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 does not explicitly mention alternatives, but it clearly implies usage contexts: when you need to screen stocks by criteria. It also proactively directs the user to list_screener_metrics and list_industries for metric/industry codes, which is valuable guidance. It does not state when not to use this tool, but given the breadth of the screener functionality, the omission is minor.

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