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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond the annotations: the large payload warning ('a 10-K comes back as roughly 19 items of full prose') and the return structure (items with number, title, text, plus filing_url and accession_number). This goes beyond what the annotations provide, though it doesn't address auth, rate limits, or error cases.

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 four sentences with no redundant phrasing. It front-loads the purpose, then concisely covers required vs. optional parameters, return shape, a practical size caveat, and the sibling-tool pointer. Every sentence earns its place.

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?

Given the output schema already documents the return shape, the description still adds the crucial size warning and the routing to get_financial_filings. It tells the agent exactly when to use this tool, how to narrow the request, and what to expect in terms of payload size. No critical information is missing for a read-only retrieval tool.

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% – every parameter already has a description in the schema, including which filing types each parameter applies to (e.g., quarter for 10-Q, accession_number for 8-K). The description merely restates the required parameters and the optional narrowing parameters without adding new semantic details. It meets the baseline but doesn't significantly enhance parameter understanding beyond the schema.

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 and resource: 'The full text of the numbered items inside one SEC filing.' It clearly differentiates from the sibling get_financial_filings by stating that the sibling is for finding which filing to open, while this tool retrieves the items within a filing.

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?

It explicitly names the alternative get_financial_filings and states when to use it ('To find which filing to open in the first place'). It also gives actionable guidance on when to request a specific item vs. the whole document via the size warning ('request a specific item rather than pulling everything unless you truly need the whole document').

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