companies-house-screening-mcp

Find a company

find_company

Read-onlyIdempotent

Search Companies House for a UK company by name, trading name, or number. Get status, type, and incorporation date to tell similarly named businesses apart and identify the correct match.

Instructions

Search Companies House for a UK company by name, trading name or number. Start here whenever you have a name rather than a number, because every other tool in this server needs the number. Returns a shortlist with status, type and incorporation date so that companies with similar names can be told apart. When disambiguation_needed is true, ask the user which one they meant instead of taking the first result — dozens of live companies share a name, and picking the wrong one produces a confident answer about the wrong business.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	Company name, partial name, or company number.
`verbose`	No	Also return the untouched Companies House payload under `raw`, alongside the shaped result. Roughly two and a half times the size; use it only when a field you need is missing from the shaped result.
`start_index`	No	Zero-based offset into the full result set. Use pagination.has_more to decide.
`items_per_page`	No	How many records to return. Defaults to the API default; the maximum is 100.

Output Schema

TableJSON Schema

Name	Required	Description
`raw`	No	The untouched Companies House payload. Present only when verbose was true.
`meta`	Yes	Provenance and budget for this answer.
`query`	Yes
`companies`	Yes
`pagination`	Yes	Where this page sits in the full result set.
`exact_name_match`	No	Company number whose name matches the query exactly. Absent if none did.
`disambiguation_needed`	Yes	More than one candidate and no exact name match. Ask the user which one they meant.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.4.0Sep 5, 2026

addedInput schema / properties / query / maxLength
```
Added value: +256
```

changedOutput schema / properties / meta / properties / licence / description

Previous value: -"Companies House data is Open Government Licence v3.0."New value: +"OGL v3.0 applies to eligible public-sector information. Personal data and other OGL exclusions are not licensed by this label; applicable data-protection duties still apply."

First observedv0.2.0Aug 30, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive, so the bar for additional disclosure is met. The description goes beyond annotations by explaining the shortlist contents, the disambiguation flag, and the real risk of confidently answering about the wrong company when names collide. This is valuable behavioral context not present in the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each earning its place: the first states the core function, the second gives routing guidance, and the third warns about a critical failure mode. It is front-loaded with the action and resource, and there is no filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with a 100%-covered schema, an output schema, and strong annotations, the description is complete. It covers purpose, when to use it, what results look like, and how to handle ambiguity. Nothing needed for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds no new parameter semantics beyond what the schema already provides, though it does reinforce that the query can be a name, trading name, or number, which matches the schema. Baseline 3 is appropriate because the schema carries the full burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Search Companies House for a UK company'), specific inputs (name, trading name or number), and a specific output (shortlist with status, type, incorporation date). It distinguishes this tool from siblings by explicitly positioning it as the starting point when you have a name rather than a number, which differentiates it from get_company and similar number-based tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives direct usage guidance: use this tool whenever you have a name rather than a number, because every other tool in the server needs the number. It also gives a concrete behavioral rule: when disambiguation_needed is true, ask the user which company they meant rather than blindly taking the first result.

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

Deploy Server