query_excel

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), lowering the burden on the description. The description adds genuine behavioral context: local execution without HTTP, the upstream file source, and support for two distinct filter formats (simple column_max/min and nested max/min objects). No contradictions with 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 purpose statement and organized into clear sections (purpose, filter formats, args). Every line carries information, including defaults. It has a minor internal inconsistency where the Args note says filters use column_name_max/min format while the detailed example uses nested objects, but overall it is efficient and well-structured.

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 5-parameter tool with zero schema descriptions, the description covers the purpose, input source, filter syntax, parameter defaults, and return limits. An output schema exists, so return-value documentation is unnecessary. The main gaps are minor: a slight inconsistency between the stated filter format and the detailed example, and no listing of which snapshot columns are filterable.

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 burden, and it delivers: every parameter (file_path, filters, sort_by, descending, limit) is described in the Args section, including concrete examples, format guidance, and defaults (descending=True, limit=30). The two filter-format examples are especially valuable because the schema only declares filters as a generic object with no structure.

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 uses a specific verb ('filter') and a specific resource ('stock items from saved Excel snapshots produced by scan_to_excel'). It distinguishes itself from the many live-data sibling tools by explicitly stating this performs local filtering without HTTP, and the reference to scan_to_excel as the upstream producer makes its role in the pipeline 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 implies the workflow context: use it after scan_to_excel to filter saved snapshots locally, and it contrasts itself with HTTP-based queries ('HTTP 없이 빠름'). However, it never explicitly names an alternative or states when not to use it, despite dozens of screening/ranking siblings (screen_by_flow, get_market_cap_ranking, get_us_screener). The guidance is serviceable but left to inference.

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