stock_screener

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

Annotations already flag readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond annotations: 'single upstream request', 'server-side descending sort over the WHOLE market', the 'price is current/last close' semantic, local-currency behavior (with KRW example), and the return-envelope structure. An agent calling this knows exactly what side effects and data semantics to expect.

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 docstring-style Args/Returns layout is scannable and front-loaded with intent. Every clause earns its place, from the parenthetical 'single upstream request' caveat on limit to the 'KRW for korea' clarification. The sort_by example is the longest sentence but conveys critical semantics that could not be abbreviated. No redundancy with the schema since the schema has no descriptions.

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?

With no output schema present, the description correctly carries the return-format burden — and does so thoroughly: the envelope keys (total_matches, returned, rows), row-level fields, and the meaning of open/high/low relative to price are all stated. The only minor omissions are error behavior for invalid country values and an explicit statement about rate limiting, but for a read-only screener this is fully adequate.

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 carries the full documentation burden — and it delivers. Every parameter gets meaning beyond its name: country gets a TradingView market-name note and examples; limit gets max-2000 plus ranking semantics; sort_by gets the full semantics of each value; exclude_otc and compact each explain the trade-off and intended use. Parameter names in the schema would be insufficient; the description fully compensates.

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 opening line names a specific verb (screen), resource (stocks), and the qualifying scope ('by share type'). It also anchors itself as the API twin of TradingView's 'Common stock' / 'Preferred stock' filter, which immediately signals its purpose relative to the many scanner siblings. Together with the title, an agent can distinguish this from the scanner tools without inspecting the schema.

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 gives rich intra-tool usage context: sort_by is explained with a concrete example showing server-side whole-market behavior, compact is positioned 'for bulk price feeds', and exclude_otc explains the 'US venue' vs 'US company' distinction. However, it never explicitly says when NOT to use this tool or names a sibling alternative (e.g., egx_stock_screener or the scanners), so selection guidance across tools is left implicit.

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