Query SEC Sector Peers

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

The description adds value beyond the annotations. While annotations declare 'readOnlyHint: true' and 'destructiveHint: false', the description explains the dynamic derivation mechanism (SIC codes, 10-K disclosures) and that results are certified (XBLR). It does not mention rate limits or pagination, but the output schema likely covers structure. No contradiction 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 two sentences long, front-loading the main verb and purpose. Every sentence adds distinct value: the first defines what it does and its data source, the second gives usage guidance. No redundancies or filler. Perfectly sized for a CEO.

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 has 5 parameters (100% schema coverage) and an output schema, so the description doesn't need to explain return values. The description covers purpose, derivation method, and use case. However, with 5 parameters and a dynamic peer group, a hint about how 'limit' or 'period' affect results might be helpful but is not critical. The context is nearly complete.

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 all 5 parameters are documented in the schema. The description itself mentions no parameters explicitly, but the schema's own descriptions are clear and sufficient (e.g., 'sector_or_industry' includes examples). The description does not add new parameter-level meaning, but with complete schema coverage, baseline 3 applies; the tool benefits from the detailed parameter examples in the schema, justifying a 4 for effective overall understanding.

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 explicitly states the tool returns 'certified SEC EDGAR XBRL metrics across an industry peer group' derived from dynamic sources like SIC codes and business segment disclosures. This clearly distinguishes it from siblings like 'query_sec_metric_exact' (which likely focuses on a single company or metric) and 'query_financial_sec' (possibly a broader query). The verb 'returns' and resource 'peer group metrics' are specific and actionable.

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 recommends use cases: 'Use this for sector screening or when no specific company ticker is provided.' This gives clear when-to-use guidance. However, it does not mention when NOT to use it or suggest alternatives among the siblings (e.g., 'query_sec_metric_exact' for single-company queries). The exclusion guidance is implied but not stated.

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