Skip to main content
Glama
Sign In

capabilities

by com.eckari
OverviewDiscussionsAdmin

Search Companies House for UK companies by name

company_uk_search
Read-onlyIdempotent

Search the UK Companies House register by name or keyword and return matching companies with company number, register status and a derived is_active, type, incorporation and cessation dates and the register's one-line address snippet. Use when: Look up a UK company by name. Not for: You already have the company number — call company.uk.profile or company.uk.status directly. Related: company_uk_status; company_uk_profile; company_uk_directors; company_uk_owners. Price: USD 0.002/call (x402), 0.0015 (account key).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "company_uk_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
qYesCompany name or keyword to search for.
limitNoMaximum results to return (1-50). Default 10.
offsetNoZero-based offset into the register's result set for paging. Pass back page.next_offset from the previous response; page.has_more says whether there is one.

Output Schema

NameRequiredDescriptionDefault
dataYesCapability output; full JSON Schema at https://api.eckari.com/v1/capabilities/company.uk.search
metaYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added
  2. Removed
  3. Added
  4. Removed
  5. Changed9 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum results to return (1-50). Default 20."New value: +"Maximum results to return (1-50). Default 10."
    • changedInput schema / properties / offset / description
      Previous value: -"Zero-based offset into the register's result set for paging. The result list is returned whole (nothing is filtered out after reading), so offset + items.length < total_results is the end-of-list test."New value: +"Zero-based offset into the register's result set for paging. Pass back page.next_offset from the previous response; page.has_more says whether there is one."
    • removedOutput schema / properties / data / additionalProperties
      Removed value: -false
    • changedOutput schema / properties / data / description
      Previous value: -"Contains public sector information licensed under the Open Government Licence v3.0 (Companies House)."New value: +"Capability output; full JSON Schema at https://api.eckari.com/v1/capabilities/company.uk.search"
    • removedOutput schema / properties / data / properties
      Removed value: -{
-  "items": {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "address": {
-          "additionalProperties": false,
-          "properties": {
-            "address_line_1": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "address_line_2": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "care_of": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "country": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "locality": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "po_box": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "postal_code": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "premises": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "region": {
-              "type": [
-                "string",
-                "null"
-              ]
-            }
-          },
-          "type": [
-            "object",
-            "null"
-          ]
-        },
-        "address_snippet": {
-          "description": "The register's own one-line address for the result, passed through verbatim. Its component order (country before postcode) differs from the single_line rendering in company.uk.registered_office and company.uk.profile, so the two are not byte-comparable.",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "company_name": {
-          "type": "string"
-        },
-        "company_number": {
-          "type": "string"
-        },
-        "date_of_cessation": {
-          "format": "date",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "date_of_creation": {
-          "format": "date",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "match_rank": {
-          "description": "Derived; the 1-based position of this item in the register's own result ordering, continuing across pages (offset + index + 1). It records where the register placed the result and is NOT a relevance, confidence or similarity score — Eckari does not compute one. Rank 1 is not a guarantee of an exact name match.",
-          "minimum": 1,
-          "type": "integer"
-        },
-        "status": {
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "type": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "required": [
-        "match_rank",
-        "company_number",
-        "company_name",
-        "status",
-        "type",
-        "date_of_creation",
-        "address_snippet"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "offset": {
-    "type": "integer"
-  },
-  "query": {
-    "type": "string"
-  },
-  "total_results": {
-    "description": "Total matches reported by the register.",
-    "type": [
-      "integer",
-      "null"
-    ]
-  }
-}
    • removedOutput schema / properties / data / required
      Removed value: -[
-  "query",
-  "total_results",
-  "offset",
-  "items"
-]
    • addedOutput schema / properties / meta / properties / attribution_url
      Added value: +{
+  "format": "uri",
+  "type": "string"
+}
    • addedOutput schema / properties / meta / properties / retrieved_at / format
      Added value: +"date-time"
    • addedOutput schema / properties / meta / required
      Added value: +[
+  "capability",
+  "version",
+  "retrieved_at",
+  "source",
+  "freshness",
+  "request_id"
+]
  6. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, providing a strong behavioral baseline. The description adds valuable context about pricing per call and account-level discounting, which is not in annotations. However, it doesn't describe pagination behavior beyond what's hinted in the schema description for offset.

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?

Four sentences, front-loaded with the core purpose, then usage guidance and pricing. Every sentence adds value with no redundancy. Extremely efficient.

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?

Given the tool's moderate complexity (3 params, simple return), existing annotation coverage, and complete schema documentation, the description is fully adequate. It covers purpose, usage rules, behavioral traits (pricing), and relationships to siblings. The output schema exists but is not shown here, so no need to describe return values.

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% with three parameters fully described (q, limit, offset). The description adds minimal semantic value beyond listing some return fields. Baseline 3 is appropriate since the schema already does the heavy lifting.

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 clearly states it searches the UK Companies House register by name or keyword, listing specific return fields. It distinguishes itself from siblings by explicitly mentioning what not to use it for when a company number is known, and names alternative tools (company_uk_profile, company_uk_status).

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 explicitly states when to use ('Look up a UK company by name'), when not to use ('You already have the company number'), and provides clear alternatives. This level of guidance is exemplary.

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

All capabilities toolsInspect
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.

Resources