Get Company Filing History

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

The description richly discloses behaviors beyond the annotations: it fetches exactly one page, never silently truncates, reports total_count/returned/has_more truthfully, returns raw source data rather than interpreted conclusions, and distinguishes a structured not_found error from an empty result. These details are not covered by the readOnly/openWorld/idempotent hints, so the description carries crucial execution context.

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 longer than average, but every sentence earns its place: purpose, pagination contract, category narrowing, raw-data caveat, and not_found handling. The key limitation ('does NOT auto-fetch every page') is front-loaded, and the not_found discussion is substantive rather than filler.

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 description covers all critical operational dimensions: pagination contract, category filtering, raw vs interpreted data, document identifier purpose, and error handling for unknown company numbers. With an output schema present, return values don't need to be spelled out, and no essential behavior an agent would need to call this tool correctly 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?

All four parameters are already fully documented in the schema with descriptions, defaults, and enumeration examples (100% coverage), so the baseline of 3 applies. The description adds contextual value by mentioning category='mortgage'/'insolvency' and the pagination idiom, but it doesn't reveal new parameter semantics beyond what the schema already states.

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: 'Fetch one page of a company's Companies House filing chronology.' It immediately distinguishes this tool from siblings by emphasizing raw source facts, one-page pagination, and the absence of document-content fetching, so an agent can easily tell it apart.

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 contrasts with company_officers/company_psc/company_charges on auto-fetching and states that no document content is fetched, signaling when this tool is not appropriate. It also advises pagination via start_index while has_more is true and narrowing with category= for specific slices. It doesn't name company_filing_document as the document-retrieval alternative, but the mention of a future document-retrieval tool makes the boundary fairly clear.

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