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

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered before the description starts. The description adds genuinely useful behavior: the non-`ok` statuses (`not_found`, `ambiguous` with `candidates`, `invalid_input` with `field`, `upstream_error` with `retryable`), and the guarantee that `filing_url` is always present while `primary_document_url` may be null. However, much of the Returns block restates fields the output schema already carries, so the net addition beyond structured data is moderate.

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?

Well front-loaded: the one-line purpose precedes Args, Returns and Example, and each section is scannable. The Returns block is long and largely duplicates an output schema that already exists, which is the main fat. Nothing is confusing, but a tighter Returns section would earn full marks.

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 three-parameter, single-issuer lookup this is essentially complete: inputs, edge cases, ambiguity recovery path, and a worked example are all present, and the status vocabulary is deferred sensibly to server instructions. The redundancy with the output schema and the absent explicit sibling routing are the only real gaps.

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 does so thoroughly: ticker case/whitespace tolerance and `BRK.B`/`BRK-B` equivalence, `forms` exact-form-type case-insensitive matching with a concrete counterexample, and `cik` as a 1-10 digit string-or-integer disambiguator that must be listed under the ticker. It also clarifies the easily confused `report_date` versus `filing_date` distinction with a fiscal-year example.

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 sentence names a specific resource and selector: the newest SEC filing for a ticker, with EDGAR links, and later pins the ordering key to `filing_date`. That makes the single-latest semantics unmistakable. It never names the siblings `list_filings_by_year` or `list_form_types`, so the differentiation from them is left implicit rather than stated.

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?

Clear operational guidance: omit `forms` to consider every form, supply `cik` only when a prior call returned `ambiguous`, and expect `filing` null when no matching form exists. The `10-K` vs `10-K/A` exact-match rule tells the agent precisely how to scope a query. What is missing is an explicit routing statement telling the agent when to prefer `list_filings_by_year` over this tool.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial context beyond them: newest-first ordering, automatic fallback to SEC history files for older years, clamping of oversized `limit`, and the fact that a future year returns an empty 'ok' result rather than an error. It also enumerates the non-ok statuses and their payload fields.

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 lead sentence is front-loaded with purpose, ordering, and paging, and the Args/Returns/Example structure is easy to scan. It is on the long side and the Returns block partly restates what the output schema already encodes, but nearly every line carries operational meaning.

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 six-parameter, paged, multi-status tool, the description covers input semantics, paging loop, ordering, empty-result behavior, and error statuses. Nothing an agent needs in order to call it correctly and interpret the response is missing.

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 does: it defines each of the six parameters, including ticker normalization, the 1993 floor on `year`, exact-match semantics for `forms`, the server cap on `limit`, and the `offset=next_offset` paging contract.

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 first sentence states a specific verb and resource ('Filings a company submitted to the SEC during one calendar year') plus ordering and paging. It is clearly distinct from the siblings get_latest_filing and list_form_types, which an agent can rule out from the description alone.

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 gives explicit selection rules: `year` keys off filing_date not report_date (with a concrete 10-K example), `forms` is exact-match and case-insensitive, and `cik` is only for resolving an 'ambiguous' result. It does not explicitly say when to prefer this over get_latest_filing, so it stops short of full alternative routing.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses that the data is a bundled snapshot with `catalogue.generated_on` and `catalogue.quarters`, that no SEC request is made, how `filings` counts are scoped to those quarters, and when `description`/`topics` are null. The only friction is that 'No request is made to the SEC' sits in mild tension with openWorldHint=true, though this reads as a snapshot-of-external-data nuance rather than a real contradiction.

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?

Front-loaded summary line followed by clearly labeled blocks and a worked example, with zero filler prose. The `Returns:` block is somewhat redundant given a full output schema exists, but it is compact and confirms status semantics rather than restating field types.

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?

Covers purpose, argument semantics, paging loop, snapshot freshness fields, and the only non-ok status ('invalid_input' with `field`), all for a three-parameter read-only tool with an output schema. Nothing an agent needs to call it correctly or page it safely is missing.

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 coverage is 0%, so the description carries the full burden and does: `query` is case-insensitive, matched against both code and description, with illustrative patterns ('10-K' matches 10-K/A, 10-KT; '/A' matches amendments), `limit` is per-page and clamped to a server cap, and `offset` is explicitly tied to the previous result's `next_offset`. This is meaning the bare integer/string schema cannot convey.

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?

States a concrete resource and scope ('EDGAR form types (submission-type codes) filed in recent quarters, most common first') and immediately positions itself as the lookup catalogue for the `forms` argument of two named siblings. An agent can distinguish it from `list_filings_by_year` and `get_latest_filing` without opening any 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?

Explicitly says when to use it ('use this to learn which values the `forms` argument ... accepts') and names the two sibling tools whose arguments it serves, plus a concrete example invocation. No alternative-selection inference is required.

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