UK Due Diligence

Search Companies House

company_search

Read-onlyIdempotent

Search the Companies House register by company name or keyword.

Returns a paginated list of matching companies with name, number, status, incorporation date, and registered address. SIC codes are not reliably returned by search; use company_profile for SIC codes. Use company_profile for the full record once you have the company number. Re-call with start_index=start_index+items_per_page to fetch the next page.

Input Schema

Name	Required	Description
`query`	Yes	Company name or keyword to search for
`start_index`	No	Pagination offset. Default 0.
`company_type`	No	Filter by company type (e.g. 'ltd', 'llp'). Omit to search all.
`company_status`	No	Filter by company status (e.g. 'active', 'dissolved'). Omit to search all.
`items_per_page`	No	Number of results to return (max 100). Default 20.

Output Schema

Name	Required	Description
`items`	No	Matching companies. Use the `company_number` field to call company_profile, company_officers, or company_psc for full detail.
`query`	Yes	The query string that was searched.
`has_more`	Yes	True if more results exist beyond this page. Re-call with start_index=start_index+items_per_page to fetch the next page.
`returned`	Yes	Number of items actually returned on this page.
`start_index`	Yes	Number of results skipped before this page (upstream start_index).
`total_results`	Yes	Total matching companies in Companies House (server-side).
`items_per_page`	Yes	Page size requested from the API for this call.

Schema Changelog

Changes observed during successful MCP inspections.

AddedMay 16, 2026
RemovedMay 16, 2026

Changed15 schema fields changedApr 16, 2026

changedInput schema / properties / items_per_page / description

Previous value: -"Number of results to return (max 100)"New value: +"Number of results to return (max 100). Default 20."

removedInput schema / properties / response_format

Removed value: -{
-  "default": "markdown",
-  "description": "Output format: 'markdown' or 'json'",
-  "type": "string"
-}

changedInput schema / properties / start_index / description

Previous value: -"Pagination offset"New value: +"Pagination offset. Default 0."

addedInput schema / properties / start_index / maximum
```
Added value: +10000
```

changedOutput schema / description

Previous value: -"Generic wrapper for non-object return types."New value: +"Paginated result of a Companies House company search."

addedOutput schema / properties / has_more

Added value: +{
+  "description": "True if more results exist beyond this page. Re-call with start_index=start_index+items_per_page to fetch the next page.",
+  "type": "boolean"
+}

addedOutput schema / properties / items

Added value: +{
+  "description": "Matching companies. Use the `company_number` field to call company_profile, company_officers, or company_psc for full detail.",
+  "items": {
+    "description": "A single entry in a Companies House search result.",
+    "properties": {
+      "address": {
+        "additionalProperties": true,
+        "description": "Registered office address as returned by the Companies House API.",
+        "type": "object"
+      },
+      "company_number": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Companies House company number (e.g. '12345678')."
+      },
+      "company_status": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Company status (e.g. 'active', 'dissolved', 'liquidation')."
+      },
+      "company_type": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Companies House company type code (e.g. 'ltd', 'plc', 'llp')."
+      },
+      "date_of_creation": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Incorporation date in ISO format (YYYY-MM-DD)."
+      },
+      "description": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Short upstream description (usually number + status + creation date)."
+      },
+      "sic_codes": {
+        "description": "Standard Industrial Classification codes associated with the company.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "title": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Registered company name."
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / items_per_page

Added value: +{
+  "description": "Page size requested from the API for this call.",
+  "type": "integer"
+}

addedOutput schema / properties / query

Added value: +{
+  "description": "The query string that was searched.",
+  "type": "string"
+}

removedOutput schema / properties / result

Removed value: -{
-  "type": "string"
-}

addedOutput schema / properties / returned

Added value: +{
+  "description": "Number of items actually returned on this page.",
+  "type": "integer"
+}

addedOutput schema / properties / start_index

Added value: +{
+  "description": "Number of results skipped before this page (upstream start_index).",
+  "type": "integer"
+}

addedOutput schema / properties / total_results

Added value: +{
+  "description": "Total matching companies in Companies House (server-side).",
+  "type": "integer"
+}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "query",
+  "total_results",
+  "start_index",
+  "items_per_page",
+  "returned",
+  "has_more"
+]

removedOutput schema / x-fastmcp-wrap-result
```
Removed value: -true
```

First observedApr 14, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely earned context: a data-quality caveat that SIC codes are not reliably returned by search, plus the paging protocol. It doesn't discuss result caps or total-count behavior, 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.

Conciseness4/5

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

Front-loaded with purpose, then the SIC caveat, then the routing advice, then paging — logical order with no filler. Slight redundancy in enumerating return fields (name, number, status, incorporation date, address) when an output schema already exists.

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?

Covers purpose, filtering intent, the SIC pitfall, sibling routing and pagination — everything an agent needs to call it correctly and decide what to do with the results. Return formatting is already handled by the output schema, so the enumeration is bonus rather than necessity.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3. The description goes beyond it by explaining the relationship between start_index and items_per_page as a paging loop rather than two independent fields, which the schema does not express.

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?

States a specific verb+resource ('Search the Companies House register by company name or keyword') and immediately scopes it against the sibling company_profile for full records. An agent can tell search vs. profile lookup apart 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.

Usage Guidelines5/5

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

Names the alternative (company_profile) twice with explicit conditions: use it for SIC codes, and use it once you have the company number. It also gives a concrete pagination recipe ('re-call with start_index=start_index+items_per_page'), which is the 'when to call again' guidance most search tools omit.

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

All UK Due Diligence tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.