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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: dynamic credit cost per request (89-1825), auto-clamping of lookback with _warnings, silent exclusion of out-of-coverage companies with _warnings, and the Pro+ classification block. It does not describe the full response shape, but with no output schema and a complex tool, the cost and warning behaviors are the most decision-relevant traits and they are disclosed.

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 dense but well-organized: it front-loads the required 'where' shape, then operators, then temporal modifiers, then optional parameters, then cost and warnings. Every sentence earns its place, and the most critical operational facts (required field, pre-run companion, cost, clamping) are prominent. It is long, but the tool is genuinely complex with 14 parameters and a nested DSL, so the length is justified. It loses one point only because a few details (e.g., 'FINANCIAL_API_DOCUMENTATION.md' reference) are marginal for an agent deciding how to call the tool.

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?

For a 14-parameter tool with nested objects, no output schema, and no enums, the description is unusually complete: it covers the required DSL, operator set, temporal modifier semantics, constraints (leaf count, depth, page limits, ticker limits), plan gating, cost range, and warning behavior. The main omissions are the exact response row shape and the full list of sortable keys, but the schema's where description covers sort_by options and the description points to list_screener_filters for metric discovery. Given the complexity, this is close to complete but not perfect.

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 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the required shape of 'where' in compact DSL form, clarifying that temporal modifiers are mutually exclusive per leaf, noting the leaf count and nesting depth limits, and explaining the effect of include_metrics_using_filing_date_price ('gates 13 valuation ratios'). It also adds the page*page_size <=500 constraint that is repeated in the schema but consolidated here. The only minor gap is that the description doesn't enumerate the sort_by options, but the schema's where description does.

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 specific verb ('Screen companies') and a precise resource ('82-metric catalog'), and the title 'Screener: search stocks by criteria' matches. It clearly distinguishes this from the many get_* and list_* siblings by framing it as a filter-DSL screening tool, and it names the companion tool list_screener_filters for discovering metric ids. An agent can tell this is the cross-sectional screener, not a timeseries or statement retrieval tool.

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 explicitly says to 'Pre-run list_screener_filters once to discover supported metric ids + operators,' which is direct when-to-use guidance. It also states the Pro plan requirement and the Pro+ gating on sectors, and it explains when _warnings is populated (lookback clamping and coverage exclusions). The sibling list includes list_screener_filters, so the routing to that companion is explicit.

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