The company registry MCP: UK Companies House company number, Norway brreg orgnr, deadlines.
Give the next occurrence of each statutory filing deadline a company faces.
country="NO" covers the Norwegian calendar (Regnskapsregisteret, Skatteetaten) for a
company looked up by organisasjonsnummer (orgnr, org.nr) in Brønnøysundregistrene /
Enhetsregisteret (brreg): årsregnskap, generalforsamling, skattemelding,
aksjonærregisteroppgaven, mva-melding, a-melding. country="GB" covers the two
Companies House obligations for a company number (CRN): the annual accounts filing and
the confirmation statement (CS01).
Pass today (YYYY-MM-DD) for a reproducible answer; it defaults to the server's
current UTC date. Quote due_date, not statutory_date. Each deadline's
applies_because states where the date came from — quote it rather than presenting a
date as unconditional fact: for Norway it names the legal form or flag and any
assumption behind a computed date, and for the UK it says whether the date is
Companies House's own published figure or one this tool computed from the statutory
period. UK dates never roll forward off a weekend or bank holiday, so due_date
equals statutory_date there; days_until goes negative for a filing Companies House
still shows as overdue rather than rolling it to the next cycle. An empty deadlines
list is a real answer — for Norway a bankrupt, deleted or compulsorily-liquidated
entity or a branch/sub-unit, and for the UK any company whose status is not active —
and notes explains why.
On error, this tool raises with the error text {"error": {"code", "message", "hint"}}. bad_request means today was not YYYY-MM-DD — fix the format and
retry. Any lookup_company error code (invalid_id, not_found,
unsupported_country, upstream_error, upstream_timeout) can also surface here,
since this tool looks the entity up first — follow that code's hint.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The company's national identifier. Norway (country='NO'): a nine-digit organisasjonsnummer (orgnr), e.g. '923609016'; spaces, dots and a 'NO...MVA' VAT suffix are accepted and normalised. United Kingdom (country='GB'): a Companies House company number (CRN), eight characters, e.g. '00445790' or 'OC303675'; a short number is zero-padded for you. | |
| today | No | Date to compute deadlines from, YYYY-MM-DD. Defaults to the server's current UTC date — pass it explicitly for a reproducible answer. A value that is not YYYY-MM-DD is a bad_request naming the required format. | |
| country | No | ISO-3166-1 alpha-2 country code. 'NO' = Norway (Brønnøysundregistrene / Enhetsregisteret), 'GB' = United Kingdom (Companies House). 'UK' is not a country code here and is rejected. Call list_countries for the current set rather than hard-coding one. | NO |
| Name | Required | Description |
|---|---|---|
| notes | No | Caveats to surface to the user, carried over from the company report: why the list is empty, an unclassified legal form, a status that suspends filing. |
| today | Yes | The date 'next occurrence' was computed from, inclusive. Echoed back so the answer is reproducible and an agent can tell a cached answer from a fresh one. |
| country | Yes | ISO-3166-1 alpha-2, upper-case. |
| registry | Yes | Registry slug, e.g. 'brreg'. |
| deadlines | No | One entry per obligation kind, always the next occurrence, sorted by due_date. An empty list is a real answer, not an error — read `notes` for why. |
| company_id | Yes | Canonical national identifier the deadlines were computed for. |
| company_name | No | Registered name, so the caller can echo it back to a user. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/open-world annotations, the description discloses substantial behavior: no weekend/bank-holiday rolling, negative days_until for overdue filings, empty deadlines as a legitimate answer with notes explaining why, and a detailed error contract including propagated lookup_company codes. This is far beyond what annotations supply.
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 long but organized into front-loaded purpose, country scope, output interpretation, and error handling. It earns its length for a complex two-country tool, though a few points repeat the schema's country and today descriptions.
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 multi-country deadline tool, it covers country-specific legal references, edge cases (bankrupt/deleted entities, inactive UK companies), reproducibility, error surface, and output caveats. An output schema exists, but the description still explains the nuanced meaning of due_date, statutory_date, days_until, and empty lists, leaving no obvious gap for an agent to call it 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%, and the schema already documents id normalization, today's format/default, and country meaning, so the description need not compensate. The prose mostly restates or reinforces this (e.g., bad_request for bad today) and adds output-usage guidance rather than new input-parameter 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?
Opens with a specific verb+resource: 'Give the next occurrence of each statutory filing deadline a company faces.' It then details the country-specific scope (Norway vs UK calendars) and names the registries involved, making the tool's job unambiguous and distinct from entity lookup/search siblings.
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 gives actionable context: pass today for reproducibility, quote due_date rather than statutory_date, and call list_countries for current set. It does not explicitly state when to choose this over lookup_company or search_company, though the distinct deadline purpose is clear from the opening sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ChatGPT connector alias; other clients should prefer lookup_company plus
company_deadlines, which return the CompanyReport and DeadlineReport shapes directly.
Takes one id from search — "{COUNTRY}:{identifier}", e.g. "NO:923609016" — and returns
that company's register record and statutory filing deadlines as readable text, with both
full JSON documents in metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | An `id` from a `search` result: '{COUNTRY}:{identifier}', e.g. 'NO:923609016' or 'GB:00445790'. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| text | Yes | |
| title | Yes | |
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: the output is readable text for the register record and deadlines, and both full JSON documents are included in `metadata`. This goes beyond annotations and helps the agent understand the response shape.
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 three sentences with no wasted words. It front-loads the alias clarification, then gives the parameter constraint and return behavior. Every sentence contributes essential guidance.
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 single-parameter read-only tool with a rich output schema and detailed annotations, this description is complete. It tells the agent when to use it, what input to provide, and what output to expect, leaving no critical gap.
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 schema already documents the `id` format with examples, so the baseline is 3. The description adds value by explicitly stating that the `id` comes from a `search` result and showing the exact `{COUNTRY}:{identifier}` pattern, reinforcing parameter provenance.
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?
The description clearly states that `fetch` is a ChatGPT connector alias for `lookup_company` and specifies what it returns: a company's register record and statutory filing deadlines. It distinguishes itself from the sibling tools by noting that other clients should prefer `lookup_company` plus `company_deadlines`.
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 explicitly says when to use this tool (ChatGPT connector) and when not to (other clients should use `lookup_company` plus `company_deadlines`). It also explains that the `id` comes from a `search` result, giving clear invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every national company registry this service can answer for right now, plus
each one's identifier scheme (id_scheme, id_example, id_description), source URL,
licence, and whether the upstream register needs a credential (requires_api_key, and
api_key_env naming the environment variable that must be set for it).
Call this before your first lookup in a country you have not used here before, or whenever a user names a country you are unsure is supported — never hard-code a country list of your own, since it grows as registry modules are added with no change to any other tool's shape. Stub/example modules are hidden; only registries that actually answer are listed. This tool has no error mode; a failure here is a bug, not something to retry differently.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| countries | No | One row per registry that can answer right now, sorted by country code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, the description discloses hidden stub modules, the live-only nature of results, credential-related fields, and the absence of an error mode. This gives the agent important behavioral expectations not encoded in annotations.
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 dense but every sentence earns its place: scope, output fields, usage timing, anti-hard-coding guidance, hidden-module behavior, and error semantics. It is front-loaded with the core purpose and does not waste words.
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 zero-input, read-only listing tool, the description covers output fields, supported-registry behavior, credentials, and failure semantics. An output schema exists for return values, and the description adds the contextual information needed for correct invocation and interpretation.
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 tool has zero parameters, and the baseline for zero-parameter schemas is 4. The description appropriately focuses on output semantics instead, explaining exactly what fields will be returned and what they mean.
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?
The description uses a specific verb and resource: 'List every national company registry this service can answer for right now'. It clearly distinguishes itself from lookup/search/validation siblings by focusing on enumeration of supported registries rather than querying a company.
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?
Explicit when-to-use guidance is provided: call before the first lookup in an unfamiliar country, or whenever the user names a country the agent is unsure about. It also warns not to hard-code a country list, giving a clear boundary that prevents misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a company by its national identifier and get the full CompanyReport — legal form, status, address, VAT registration where the register publishes it, board and accounts duties, employees, and more.
country="NO" is the norway company lookup for the norwegian business registry:
Brønnøysundregistrene / Enhetsregisteret (brreg), by organisasjonsnummer (orgnr,
org.nr). country="GB" is the uk company lookup at Companies House, by company number
(company registration number, CRN) — eight characters, digits or a two-letter prefix
and six digits, e.g. 00445790 or OC303675; short numbers are zero-padded for you, and
"UK" is not a country code here, use "GB".
Use it once you have the identifier — from the user, an invoice, a contract, or a
search_company hit's id; the identifier is normalised for you, so spaces, dots and
a Norwegian VAT suffix ('NO...MVA') are all accepted. Call list_countries if you are
unsure a country is supported. Read the returned notes before acting on the result —
it carries caveats such as bankruptcy, dissolution, a deleted entity, or an
unclassified legal form.
This tool does not perform sanctions, PEP or adverse-media screening, and it does not verify bank account details — it returns identity and filing data from the national register only, never a compliance clearance or a confirmed payment detail.
On error, this tool raises with the error text {"error": {"code", "message", "hint"}} (DECISIONS.md D-007). invalid_id means the identifier is malformed —
fix it or call search_company with the company name instead of retrying the same
string. not_found means the identifier is well-formed but no such entity exists —
call search_company. unsupported_country means no module exists for that country
yet — call list_countries. upstream_error/upstream_timeout means the national
register is unavailable; it has already been retried once here, so wait roughly a
minute before trying again yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The company's national identifier. Norway (country='NO'): a nine-digit organisasjonsnummer (orgnr), e.g. '923609016'; spaces, dots and a 'NO...MVA' VAT suffix are accepted and normalised. United Kingdom (country='GB'): a Companies House company number (CRN), eight characters, e.g. '00445790' or 'OC303675'; a short number is zero-padded for you. | |
| country | No | ISO-3166-1 alpha-2 country code. 'NO' = Norway (Brønnøysundregistrene / Enhetsregisteret), 'GB' = United Kingdom (Companies House). 'UK' is not a country code here and is rejected. Call list_countries for the current set rather than hard-coding one. | NO |
| Name | Required | Description |
|---|---|---|
| id | Yes | Canonical national identifier, digits/letters only, no spaces or dots. |
| name | Yes | Current registered name. |
| No | Contact email as registered. | |
| notes | No | Caveats an agent should surface to the user, plain English, one per item. |
| phone | No | Contact phone as registered. |
| cached | No | True when served from our cache rather than a live fetch. |
| sector | No | Institutional sector description. |
| source | No | Human-readable source name, e.g. 'Enhetsregisteret (brreg.no)'. |
| status | No | Normalised lifecycle status. |
| country | Yes | ISO-3166-1 alpha-2, upper-case, e.g. 'NO'. |
| license | No | Licence of the upstream data, e.g. 'NLOD 2.0'. |
| purpose | No | Statutory purpose / objects clause, joined into one string. |
| website | No | Website as registered. |
| activity | No | Free-text description of actual activity. |
| in_group | No | Part of a corporate group. |
| registry | Yes | Registry slug, e.g. 'brreg'. |
| employees | No | Registered number of employees. None = not reported. |
| id_scheme | No | Name of the identifier scheme, e.g. 'organisasjonsnummer'. |
| is_active | No | Convenience mirror of `status == active`, so agents need no enum table. |
| parent_id | No | Identifier of the parent/owning entity, if any. |
| registers | No | Other national sub-registers this entity is or is not in, keyed by a lower-case slug, e.g. {'stiftelsesregisteret': false}. |
| confidence | No | How sure we are this record is the entity the caller meant (D-005). |
| fetched_at | No | UTC timestamp of the live fetch this record came from. |
| founded_at | No | Incorporation / foundation date. |
| is_subunit | No | True when this record is a branch/sub-unit, not a legal entity. |
| legal_form | No | English label, e.g. 'Private limited company'. |
| source_url | No | Direct URL of the upstream record, for citation. |
| vat_number | No | VAT identifier if it differs from `id` (Norway: id + 'MVA'). |
| sector_code | No | Institutional sector code. |
| id_formatted | No | The identifier as a local would write it, e.g. '923 609 016'. |
| registered_at | No | Date first entered in the central register. |
| share_capital | No | Registered share capital. |
| status_detail | No | One sentence in English explaining the status and the flag it came from. |
| has_board_duty | No | True when this legal form must have a registered board. |
| industry_codes | No | Industry classifications, primary first. |
| postal_address | No | Postal address. |
| previous_names | No | Former registered names, newest first. |
| vat_registered | No | Registered for VAT (Norway: Merverdiavgiftsregisteret). |
| bankruptcy_date | No | Date bankruptcy was opened. |
| deregistered_at | No | Date the entity was deleted from the register. |
| legal_form_code | No | National legal-form code, e.g. 'AS', 'ASA', 'ENK'. |
| business_address | No | Visiting/registered office. |
| confidence_basis | No | Why that confidence, e.g. 'exact identifier lookup'. |
| legal_form_local | No | Local label, e.g. 'Aksjeselskap'. |
| limited_liability | No | True when owners are not personally liable for debts. |
| vat_registered_at | No | Date of VAT registration. |
| employees_reported | No | Whether the registry holds an employee figure at all (distinguishes 0 from unknown). |
| published_deadlines | No | Filing dates the upstream register publishes for this entity itself, carried verbatim. Empty for a register that publishes none — most of them. This is the input `Registry.deadlines(report, today)` needs to prefer the register's own figure over any calculation (DECISIONS.md D-018), and it is what keeps that method the pure function of (report, today) its contract promises. |
| in_business_register | No | Listed in the commercial register (Norway: Foretaksregisteret). |
| share_capital_currency | No | ISO-4217 code for `share_capital`. |
| has_annual_accounts_duty | No | True when this legal form must file annual accounts with the state. |
| last_annual_accounts_year | No | Most recent financial year for which accounts were filed. |
| business_register_registered_at | No | Date entered in the commercial/business register, where that is separate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotentHint annotations, the description discloses normalisation of identifiers, caveats in the returned notes, explicit non-capabilities (no sanctions/PEP/adverse-media screening, no bank verification), and a detailed error model with codes and retry guidance. This substantially exceeds what annotations alone convey.
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 long but front-loaded with the core operation, then country formats, then usage conditions, then exclusions and error handling. Every sentence carries distinct information relevant to calling the tool correctly.
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 tool with national-specific identifier formats, error semantics, and compliance caveats, the description covers all necessary context. The output schema exists, so return-value details need not be repeated, and no meaningful gap remains for selecting or invoking the 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?
The schema already covers both parameters in full detail (100% coverage), including formats, examples, and country handling, so the baseline is 3. The description mostly restates schema content (zero-padding, VAT suffix, 'UK' rejected) rather than adding new parameter meaning.
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?
The description uses a specific verb and resource: 'Look up a company by its national identifier and get the full CompanyReport', and clearly differentiates itself from search_company by stating lookup is for when the identifier is already known. It also names the national registers for NO and GB, so an agent can distinguish the tool from siblings without opening the 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?
It explicitly states when to use the tool: 'Use it once you have the identifier — from the user, an invoice, a contract, or a search_company hit's id'. It also prescribes alternatives: call search_company for invalid_id/not_found and list_countries for unsupported countries, making the routing unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ChatGPT connector alias; other clients should prefer search_company, which takes an
explicit country and returns the full SearchResult. Finds companies in this server's
national business registers (Norway, United Kingdom) from one free-text query — a name, a
national identifier, or a name plus a country — and returns {"results": [{"id", "title",
"url"}]}. Pass a result's id to fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look for: a company name, a national identifier, or a name plus a country, e.g. 'Equinor', '923609016', 'Tesco United Kingdom'. |
| Name | Required | Description |
|---|---|---|
| results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context: it is a ChatGPT connector alias, scopes the search to Norway and UK registers, accepts a free-text query, and returns a condensed result list rather than the full SearchResult. This goes beyond the annotations, though it does not detail error conditions or edge cases.
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 compact sentences with no filler: the first declares the alias and preferred alternative, the second defines the search scope and output, and the third gives the next step. Information is front-loaded and each sentence 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?
For a single-parameter search tool with a rich input schema, an output schema, and strong annotations, the description is complete. It explains the alias relationship, scope, accepted query forms, return format, and onward routing to `fetch`. No critical information needed to select or invoke the tool 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?
The input schema already provides 100% coverage with examples and a detailed description of the `query` parameter. The description reinforces the free-text semantics and the three allowed query forms, but does not add meaning beyond what the schema already conveys, so baseline 3 is appropriate.
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?
The description names the resource (companies in national business registers) and the action (finds from a free-text query), and explicitly identifies the tool as an alias for `search_company`, distinguishing it from its sibling. It also specifies the input forms (name, identifier, name plus country) and the output shape, leaving no ambiguity about what the tool does.
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 explicitly tells other clients to prefer `search_company` and explains why: it takes an explicit `country` and returns the full SearchResult. It also directs the agent to pass a result's `id` to `fetch`, providing clear routing and follow-up guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search a national company register by name, when you have a name rather than an identifier.
country="NO" searches Brønnøysundregistrene / Enhetsregisteret (brreg) for Norwegian
companies — the norway company lookup tool for the norwegian business registry when the
organisasjonsnummer (orgnr, org.nr) is not yet known. country="GB" is the uk company
search: Companies House by company name, returning each hit's company number
(company registration number, CRN).
Use it when a user gives you a company name, then call lookup_company with the id
of the right hit for the full report — a search hit is deliberately thin (name, legal
form, status, city) and must not be acted on directly. limit is 1-100 (default 10).
Hits arrive in the register's own relevance order, so read each hit's confidence
rather than assuming the first row is the best one. Zero hits is not an error: hits
is [], total is 0, and hint says what to try next — Norwegian names are
registered upper-case and often carry an 'AS', 'ASA' or 'NUF' suffix, and UK names a
'LIMITED', 'LTD', 'PLC' or 'LLP' one, worth dropping before concluding a company does
not exist.
On error, this tool raises with the error text {"error": {"code", "message", "hint"}}. bad_request means limit was out of range or name was empty — fix and
retry. unsupported_country means call list_countries first.
upstream_error/upstream_timeout means the national register is unavailable; wait
roughly a minute and retry at most once more.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Company name to search for, free text — not an identifier. Use lookup_company once you have the id of the right hit. | |
| limit | No | Maximum hits to return. 1-100, default 10; a value outside that range is a bad_request, not a silent clamp. | |
| country | No | ISO-3166-1 alpha-2 country code. 'NO' = Norway (Brønnøysundregistrene / Enhetsregisteret), 'GB' = United Kingdom (Companies House). 'UK' is not a country code here and is rejected. Call list_countries for the current set rather than hard-coding one. | NO |
| Name | Required | Description |
|---|---|---|
| hint | No | What to do next, e.g. 'call lookup_company with the id of the right hit'. |
| hits | No | Best matches, best first: always sorted by `confidence` descending. Hits that score equally keep the order the upstream register returned them in. |
| query | Yes | The name that was searched for. |
| total | No | Total matches upstream, which may exceed len(hits). |
| cached | No | Served from cache. |
| country | Yes | ISO-3166-1 alpha-2, upper-case. |
| registry | Yes | Registry slug. |
| truncated | No | True when `total` exceeds the returned hits. |
| fetched_at | No | UTC timestamp of the fetch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotentHint annotations, the description discloses the error contract (raises with an object containing code, message, and hint), per-error recovery steps (bad_request fix-and-retry, upstream retry at most once after ~a minute), register-native relevance ordering with a confidence caveat, and zero-hit semantics (hits is [], total is 0, hint suggests dropping AS/LTD-type suffixes). No contradiction with the annotations.
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 is front-loaded and the text is organized into clear paragraphs: purpose and country mapping, workflow and result semantics, then error recovery. It is long (~250 words), and a phrase like 'the norway company lookup tool for the norwegian business registry' is mildly redundant, but nearly every other sentence carries distinct operational 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?
With an output schema present and safety annotations covering side effects, the description covers the full call-and-interpret loop: search semantics, country mapping, thin-hit warning, ordering, empty results, naming conventions, and error recovery. Nothing an agent needs to invoke this tool correctly or act on its results 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 coverage is 100%, so the baseline is 3; the description still adds registry-specific meaning beyond the schema — country="NO" maps to Brønnøysundregistrene/Enhetsregisteret and country="GB" to Companies House returning a company number (CRN). It also ties limit to the register's relevance order, helping the agent interpret result ranking rather than just validating input ranges.
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?
The first sentence states a specific verb and resource ('Search a national company register by name') with an explicit selection condition ('when you have a name rather than an identifier'). It clearly distinguishes itself from the sibling lookup_company, which is the tool to call once an identifier 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?
The description explicitly routes the agent: use search_company when the user gives a company name, then call lookup_company with the id of the right hit for the full report. It also names fallbacks (list_countries for unsupported_country) and warns that results are thin and must not be acted on directly, leaving no ambiguity about the search-to-report workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a national company identifier is well-formed — no network call.
country="NO" checksum-checks a Norwegian organisasjonsnummer (orgnr, org.nr) for
Brønnøysundregistrene / Enhetsregisteret (brreg); this is the cheap norway company
lookup pre-check for the norwegian business registry. country="GB" shape-checks and
normalises a UK company number (company registration number, CRN) for Companies House:
it zero-pads a short number ('445790' → '00445790') and upper-cases a prefix
('oc303675' → 'OC303675'). A CRN has no check digit, so a GB valid: true means the
shape is right and nothing more.
Use it on user input or a spreadsheet column before spending a real lookup_company
call, since it is instant and free.
Returns a ValidationResult and never raises for a malformed identifier: valid: false
comes with reason (what failed) and hint (what to do next) rather than a tool
error — this tool answers a question, it does not fail on bad input
(DECISIONS.md D-010). A valid identifier does not mean the entity exists; follow it
with lookup_company if you need facts.
The only real error here is unsupported_country (no module for that country yet —
call list_countries), raised with the error text {"error": {"code", "message", "hint"}}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The company's national identifier. Norway (country='NO'): a nine-digit organisasjonsnummer (orgnr), e.g. '923609016'; spaces, dots and a 'NO...MVA' VAT suffix are accepted and normalised. United Kingdom (country='GB'): a Companies House company number (CRN), eight characters, e.g. '00445790' or 'OC303675'; a short number is zero-padded for you. | |
| country | No | ISO-3166-1 alpha-2 country code. 'NO' = Norway (Brønnøysundregistrene / Enhetsregisteret), 'GB' = United Kingdom (Companies House). 'UK' is not a country code here and is rejected. Call list_countries for the current set rather than hard-coding one. | NO |
| Name | Required | Description |
|---|---|---|
| hint | No | What to do next when `valid` is false — the same hint the invalid_id error carries. None when valid: the next call is simply lookup. |
| input | Yes | The identifier exactly as the caller supplied it. |
| valid | Yes | True when the identifier passes this country's format and checksum. |
| reason | No | One English sentence saying why it is valid, or what failed. |
| country | Yes | ISO-3166-1 alpha-2, upper-case. |
| registry | Yes | Registry slug, e.g. 'brreg'. |
| formatted | No | The identifier as a local would write it, e.g. '923 609 016'. None when invalid. |
| id_scheme | No | Name of the identifier scheme, e.g. 'organisasjonsnummer'. |
| normalized | No | Canonical form to pass to lookup, e.g. '923609016'. None when invalid. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description is fully consistent with them. Beyond that, it discloses meaningful behavioral traits: it never raises for malformed identifiers and returns reason/hint instead of a tool error, it performs no network call, country-specific semantics (checksum vs. shape-check, zero-padding, upper-casing), and the exact error shape for unsupported_country. This far exceeds what annotations provide.
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 long (five paragraphs) but every paragraph carries distinct non-redundant information: core purpose, country behavior, usage guidance, return/error behavior, and the sole error case. It is front-loaded with the most important fact ('Check whether... no network call') and uses paragraphs as structural separators. Slight redundancy exists between title and first sentence ('no network call'), but no sentence is wasted.
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 validation tool with an output schema and full annotations, nothing essential is missing. It covers per-country validation rules, the false-positive caveat (valid ≠ exists), the correct follow-up tool, normalization details for the id parameter, and the only error condition with its payload shape. The DECISIONS.md reference adds traceability for the no-failure contract.
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 baseline is 3, but the description adds substantive meaning: it explains WHY country values behave differently (NO checksums against brreg; GB shape-only with no check digit), the normalization consequences for id ('445790' → '00445790'), and rejects 'UK'. The schema documents formats, but the description explains the validation semantics and practical implications.
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?
The opening sentence states a specific verb and resource: 'Check whether a national company identifier is well-formed — no network call.' It clearly differentiates from siblings by positioning itself as the cheap pre-check before lookup_company, and more granularly separates NO checksum validation from GB shape-checking. An agent can distinguish this from the six sibling tools without opening their schemas.
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?
Explicit when-to-use guidance is present: 'Use it on user input or a spreadsheet column before spending a real lookup_company call, since it is instant and free.' It also names the follow-up alternative ('follow it with lookup_company if you need facts'), the exclusion condition for GB ('A CRN has no check digit, so a GB valid:true means the shape is right and nothing more'), and routes unsupported countries to list_countries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
company_deadlinesfetchlist_countrieslookup_companysearchsearch_companyvalidate_company_idClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Companies House MCP — UK statutory company registry (BYO key)
Brønnøysund Register Centre (BRREG) MCP — Norway's official business register.
OpenCorporates MCP — Global company registry data (free, no auth, rate limited)
Live data from 27 official national company registries. Unmodified. For KYB and due diligence.
Add one secure layer between your agents and this server.
There are two pairs of conceptually overlapping tools: lookup_company vs validate_company_id (both take a country code and identifier, and validate_company_id explicitly positions itself as a 'pre-check' or 'cheap' version of lookup_company), and search vs search_company vs fetch vs company_deadlines (the connector aliases duplicate the canonical tools). The descriptions do disambiguate them, but an agent could reasonably confuse validate_company_id with a lightweight lookup rather than a pure format check, and the alias pair search/fetch adds unnecessary ambiguity.
Most tools follow a clear verb_noun pattern: list_countries, lookup_company, search_company, validate_company_id, company_deadlines. However, company_deadlines breaks the pattern by putting the noun first without a verb, and fetch/search are generic aliases that do not match the family's naming convention. The core set is consistent, but the deviations are noticeable.
Seven tools is within the ideal range for a domain-specific registry server. The main tools (list_countries, search_company, lookup_company, company_deadlines, validate_company_id) each earn their place. The two connector aliases (search, fetch) are somewhat redundant for non-ChatGPT clients, which slightly pads the count without adding real functionality, but the scope is still reasonable.
The tool surface covers the full lifecycle of a company-registry interaction: discover supported countries (list_countries), validate an identifier offline (validate_company_id), search by name (search_company), fetch full company data (lookup_company), and retrieve statutory deadlines (company_deadlines). There are no obvious dead ends: search returns ids that feed lookup_company, and lookup_company complements deadlines. For the stated purpose—answering company identity and filing-deadline questions from national registries—the coverage is complete.