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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial non-obvious behavior: 24 h caching, Blind Mode (officers and individual PSCs never ingested, filing events carry only category codes), 1 credit per call, and the keyless preview limit of 5 rows / 20 calls per day. This is exactly the cost/auth/privacy context an agent cannot get from the schema.

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?

Three dense sentences, front-loaded with the purpose, then the returned-field inventory, then operational constraints (Blind Mode, cache, credits). The field enumeration is long but earns its place since there is no output schema; no filler sentences.

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?

With no output schema present, the description compensates by listing the profile contents and their freshness (24 h cache), plus billing and access tiers. The remaining gap is that three of five input parameters and the paging behavior are undocumented, which an agent must resolve by reading the schema alone.

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% across 5 parameters, and the description only explains two of them (company_number and company), including a worked example that clarifies the number format. The q, page and per_page parameters are never mentioned, and page/per_page actually sit in tension with the stated "one record per call", leaving an agent unclear on whether paging applies here.

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 specific verb and resource: returns one UK company profile by number or name from the official Companies House API, and enumerates the fields returned (status, SIC codes, accounts dates, charges, PSCs). "One record per call" distinguishes it from a multi-result search, but it never names the obvious sibling query_uk_companies, so the split is inferred 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?

The phrase "One record per call, named by company_number or company" implies this is the single-entity detail lookup with a concrete example call, which is helpful. However, there is no explicit when-to-use/when-not or routing to alternatives such as query_uk_companies for search or query_uk_charities/insolvency for adjacent registers.

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