UK Companies House due diligence and KYB (Registrum)

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is handled. The description adds genuinely new behavioral context: the tool returns a single profile only (not ownership/officers/accounts) and enumerates what the returned object contains. It does not mention rate limits or failure behavior for unknown ids, keeping it short of a 5.

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?

Purpose and input format are front-loaded in the first clause, and the two long sentences each carry distinct payload (return shape vs. sibling routing). The return-value sentence is dense but justified because there is no output schema; a small amount of parenthetical nesting costs it a perfect score.

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, the description fully compensates by enumerating the return fields (id, title, url, text, metadata) and the contents of the enriched JSON profile. Combined with the sibling routing, an agent has everything needed to select and call this tool correctly.

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 100% and there is only one parameter, so the schema baseline already applies. The description still adds value by documenting an alternative accepted form ('company:<number>; a bare company number also works') that the schema example alone does not make explicit.

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 ('Fetch one UK company by an id from search') and even specifies the domain ('UK company'). It distinguishes itself from most siblings by naming which ones handle ownership, officers and accounts, though it never addresses the near-identically named sibling get_company, leaving a real ambiguity.

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 routes the agent elsewhere for adjacent needs: 'use get_bundle, get_psc, get_directors or get_financials for ownership, officers and accounts,' and scopes the tool with 'Profile only.' It also clarifies the accepted id form ('a bare company number also works'), so both when-to-use and how-to-call are covered.

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/non-destructive, but the description adds substantial behavioral context beyond them: partial results are normal, any section may be null for availability or plan reasons, compliance requires a Pro plan, financials are null without machine-readable accounts, and only a missing company yields a 404. It also warns against misreporting nulls as failures — genuine operational guidance not derivable from structured 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?

Front-loaded with purpose and the sibling-routing rule, then the parameter policy, then error semantics — a sensible ordering. It is dense and fairly long, but nearly every sentence carries distinct information; the null-handling instructions could be tightened slightly without loss.

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, the description carries the return-shape burden and does so: it enumerates the five sections, explains null semantics, notes ECCTA verification_status is passed through with its own pending-versus-overdue rules, and specifies the single error case. An agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: omitting 'include' returns all five sections, profile is always returned, and non-included sections surface as null rather than being absent. It does not add format guidance for company_number beyond what the schema already provides.

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 with scope: 'Get several views of one UK company in a single request: profile, ECCTA compliance, financials, PSCs and directors.' It then explicitly names the five sibling tools it supersedes (get_company, get_compliance, get_financials, get_psc, get_directors), so an agent can distinguish it 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?

Gives an explicit preference rule ('Prefer this over calling ... separately') with the rationale (one API call, one credit, one round trip), and states the parameter-selection policy ('Pass include to fetch only the sections you need; omit it to get all five'). No when-to-use decision is left to inference.

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: it discloses the exact field set returned and flags that some values (company_age_years, accounts.overdue) are derived/enriched rather than raw API output, which tells the agent results may differ from Companies House directly.

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?

Two sentences, no filler. The first front-loads the action, scope, and identifier; the second handles return values. Every clause 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?

With no output schema, the description does the heavy lifting by enumerating return fields and noting derived values, which is what an agent needs to interpret results. The only gap is failure behavior for unknown or malformed company numbers (e.g., not-found handling), which the description does not mention.

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?

There is only one parameter and the schema documents it fully (100% coverage, including the pattern and the zero-padding example for '00445790'). The description reinforces that the input is a Companies House number but adds no format or edge-case detail beyond the schema. Baseline 3 is appropriate when the schema carries the semantics.

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 ('Get an enriched profile for a UK company') and pins the identifier to a Companies House number, which immediately separates it from siblings like get_financials, get_directors, or get_psc. The enumeration of returned fields (status, SIC codes, accounts status, derived fields) further confirms this is the general profile retrieval tool.

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 explains what the tool returns but never says when to choose it over get_financials, get_directors, get_compliance, or search_company. The only comparative hint is that derived fields are 'not available from the raw Companies House API', which is about the upstream source, not about tool selection. No exclusions or prerequisites are given.

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 cover read-only, idempotent, open-world, and non-destructive behavior, but the description adds substantial context beyond them: the meaning of 'pending' versus 'overdue' (with an explicit warning not to report pending as a failure), the 18 November 2026 enforcement date, the 24-hour cache, and the Pro-plan requirement. This is rich behavioral and interpretive detail.

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 front-loaded with the core purpose, then adds return fields, a critical interpretation warning, and prerequisites. Every sentence carries actionable information, and the IMPORTANT warning is placed prominently rather than buried.

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, the description compensates by naming the returned counts (directors_total, directors_verified, directors_pending, directors_overdue) and the per-person unverified_persons structure. Combined with status semantics and caching, an agent has everything needed to call and interpret the tool correctly.

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 the single parameter's format and zero-padding rule are already documented in the schema. The description adds no further parameter-level syntax or constraints, so the baseline of 3 applies.

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: 'Check a UK company's ECCTA identity-verification status,' then enumerates exactly what is returned (who verified, pending, overdue). This is clearly distinguishable from siblings like get_directors or get_psc, which deal with officer/PSC listings rather than compliance status.

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?

Provides prerequisites ('Requires a Pro plan or above') and a caching caveat ('Cached for 24 hours'), which help an agent decide whether it can call the tool. However, it never explicitly says when to use this tool versus alternatives such as get_directors or get_psc, leaving usage largely implied by the purpose.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). Beyond that, the description adds real behavioral context: the register includes past as well as current officers, entries carry varied officer_role values with is_board_director=false for secretaries, and each officer carries ECCTA verification status and cross-company appointments. It stops short of noting pagination or volume limits for large registers.

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 most valuable insight, that the list is not all directors, arrives in the second sentence and is front-loaded. The closing field inventory (appointment date, resignation date, nationality, occupation, birth month/year, ECCTA status, other companies) is slightly long-winded but each item earns its place by describing the return payload.

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, the description carries the full burden of explaining return values, and it does so thoroughly: per-officer fields, the officer_role enumeration, the is_board_director flag, and nested other-company appointments. The reporting caution ('never describe the whole list as directors') closes the main correctness gap for an agent summarizing results.

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?

The single parameter is fully documented in the schema (100% coverage) with a pattern and a concrete example ('00445790' for Tesco PLC). The description adds no syntax or format detail for company_number, so this is the expected baseline where the schema carries the load.

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 ('Get the current and past officers for a UK company') and immediately clarifies the scope mismatch with the tool name, explaining it is the full officer register rather than just directors. An agent can distinguish this from get_psc or get_company 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?

The description implies when to reach for it ('full picture of an officer's corporate history in one call'), which hints at using this instead of repeated lookups, but it never names a sibling alternative or states an exclusion. Usage is inferable from the described scope rather than explicitly guided.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: a 7-day cache, the available:false path with three distinct unavailable_reason values (image_pdf, no_ixbrl_filings, dissolved), and the crucial clarification that unavailable does NOT mean the company has no accounts. It also warns that abbreviated filings carry no profit and loss.

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 with the core purpose and returned fields, then moves to caveats. It is a dense, long paragraph, but nearly every sentence carries non-obvious semantics (period_end vs filed_on, accounts_type unknown, abbreviated filings). Slightly heavy but well organized.

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?

There is no output schema, so the description carries the full burden of explaining the return shape — it does so exhaustively via the field list, data_quality block and the available:false structure. An agent has everything needed to interpret a response.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents the format, example and zero-padding rule. The description adds nothing about company_number, so the baseline 3 applies.

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 ('Get structured financial data for a UK company') plus the exact source ('parsed from its iXBRL accounts filed at Companies House'). Enumerates the returned fields, which clearly separates it from siblings like get_company, get_directors and get_compliance.

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 implies usage strongly through its content (what the data is, when the response is unavailable) but never explicitly states when to choose this over get_company or other siblings. It explains data-availability edge cases rather than routing guidance, so usage remains inferred rather than directed.

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 non-destructive. The description adds genuine behavioral value beyond them: the traversal is bounded by depth, results are per-connected-company, and each result carries name, number, status and shared directors. It does not mention result volume or pagination behavior, which would matter for depth 2.

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 sentences, front-loaded with the core action, followed by return shape then use cases. No sentence is redundant and the scoping constraint appears before the payoff detail.

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 two-parameter read tool with no output schema, the description covers purpose, traversal semantics and returned fields well. It omits expected result volume/pagination for depth 2 and any guidance on choosing depth, which the schema only partially covers.

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 baseline is 3. The description only echoes that traversals are 'up to the specified depth'; the depth semantics (1 = direct, 2 = connections of connections) and the zero-padding rule for company_number live entirely in 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?

States a specific verb and resource ('Map the corporate network connected to a UK company via shared directors') and immediately scopes it by the mechanism (shared directors) and domain (UK company). This clearly separates it from siblings like get_directors or get_company, which return entities rather than relationships.

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?

Gives clear use contexts – 'identifying corporate group structures, related party relationships, and director interlocks' – which tells an agent when this tool fits. It stops short of naming alternatives or stating when not to use it (e.g., for simple director listings use get_directors).

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavioral context beyond that: a 24-hour cache, the meaning of verification_status values including the counterintuitive case that 'pending' and 'unknown' are not compliance failures, and explicit warnings that a null company_number is not a missing value. This is rich, non-obvious disclosure.

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 purpose is front-loaded in the first sentence and the remaining content is dense, field-level semantics rather than filler. It is long but nearly every clause carries decision-relevant meaning; the trailing 'Cached for 24 hours' is slightly orphaned from the rest.

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, the description carries the full burden of explaining return values and does so thoroughly: field-by-field semantics for individual vs corporate PSCs, null-handling rules, the kind/kind_raw fallback, and registry_is_companies_house tri-state meaning. Nothing an agent needs to 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?

There is a single parameter at 100% schema description coverage, and the schema already documents the format, pattern and zero-padding rule. The description adds nothing specific about the company_number argument itself, so the baseline of 3 applies.

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 ('Get the PSC (Persons with Significant Control) register for a UK company') and immediately defines scope by describing the entity types and thresholds returned. This is clearly distinguishable from siblings like get_directors or get_psc_chain 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?

The description implies when the data is relevant (ownership/control analysis, ECCTA compliance checks) but never explicitly says when to use this versus get_psc_chain or get_directors, nor does it state any prerequisites or exclusions. Usage must be inferred from the returned-content description.

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 cover only the safety profile (readOnly/idempotent/openWorld/non-destructive), and the description adds substantial context they cannot: the full terminal_reason taxonomy, the misreading traps for unverified_registry and unknown_kind, the registry_number/registry_is_companies_house semantics, ECCTA verification fields with an explicit warning that pending/unknown are not breaches, and the credit cost reported in chain_metadata.

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 with the core action, then layered disambiguation. It is long, but nearly every sentence carries information an agent needs to interpret terminal_reason and verification fields correctly. The 'both are findings, not errors' point is stated twice, a minor redundancy.

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, the description carries the full burden and does so: it describes the returned tree, per-node fields, terminal reasons, registry attribution, identity-verification semantics, and chain_metadata cost. Nothing material for correct invocation or interpretation 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 100% and both parameters are already documented there, including the 1-10 range, default, and per-level API cost. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 ('Trace the full ownership chain for a UK company by recursively following corporate entity PSCs') and explicitly positions itself beyond the immediate PSC layer, which cleanly separates it from the sibling get_psc. An agent can select it without ambiguity.

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?

Closes with concrete use cases ('KYB checks, AML screening, or any task requiring beneficial ownership beyond the immediate PSC layer'), which implicitly routes shallow-PSC lookups to get_psc. No explicit exclusions or when-not-to-use statement, so it stops short of a 5.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real behavioral context beyond them: a hard cap of 10 results, relevance ordering, and an empty results array when nothing matches. Those result-set behaviors are not visible anywhere in the structured 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?

Three tight sentences, front-loaded with what it searches, then the return contract, then the next-step chaining instruction. Every sentence carries distinct information: result count limit, ordering, empty-state behavior, and id handoff to fetch. No 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?

With no output schema, the description correctly carries the burden of describing the return shape (results array, id/title/url fields) plus the 10-result cap and ordering. An agent has everything needed to call it and to chain into fetch. Nothing material 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?

There is a single parameter with 100% schema description coverage, so the schema already documents 'query' fully. The description's phrase 'by name or keywords' restates that semantics without adding format, syntax, or matching rules. Baseline 3 is appropriate when the schema does the heavy lifting.

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 with scope: 'Search UK companies at Companies House by name or keywords.' That is clear, but it does not distinguish itself from the sibling tool 'search_company', which an agent could easily confuse with 'search'. No differentiation language is present.

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 does give forward guidance ('Use fetch on an id to read the company'), which is genuinely useful chaining context. However, it never says when to choose this tool over the similarly named sibling search_company, nor does it state any exclusions or preconditions. Usage is implied rather than defined.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the returned field set, which is meaningful because there is no output schema, though it says nothing about result ordering or truncation behavior.

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 short sentences, zero padding, and the purpose plus return contents are front-loaded before the usage hint. Every sentence carries distinct information.

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 two-parameter read-only search with a fully documented schema, complete annotations, and no output schema, the description supplies purpose, return shape, and routing guidance. Nothing an agent needs in order to call it 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?

Schema description coverage is 100%, with both 'query' and 'limit' (including min/max and default) documented in the schema itself. The description adds no syntax, matching, or ranking guidance beyond that, so the baseline 3 applies.

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 ('Search for UK companies by name') and enumerates the returned fields (company number, status, type, registered address), so an agent knows exactly what it gets back. It also implicitly differentiates from the get_company sibling by noting it is the entry point when only a name is known.

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?

'Use this first when you only have a company name and need its company number' gives an explicit when-to-use condition and points at the natural follow-up (fetching by number). No explicit when-not or named alternative, but the routing intent is unambiguous.

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