Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Zefix MCP Server Search the Swiss commercial register for Migros in Zurich."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Search the Swiss commercial register, retrieve company and publication data, and validate Swiss UID and VAT numbers through the Model Context Protocol (MCP).
This is an independent, unofficial project. It is not operated by or affiliated with the Swiss Confederation, the Federal Office of Justice, or the Federal Statistical Office.
The server exposes nine tools over MCP's standard input/output (stdio) transport. It combines the authenticated Zefix Public REST API with the public functions of the Swiss UID Webservice.
Tool | Data source | Purpose |
| Zefix | Search by company name; optionally filter by canton, legal form, and active status. |
| Zefix, optional UID enrichment | Retrieve a company's register record and optionally enrich it with UID data. |
| Zefix | Retrieve a company's SOGC publications, newest first. |
| Zefix | Browse SOGC publications for a date, with canton and mutation filters. |
| UID Webservice | Search by organization or person name, canton, and legal form. |
| UID Webservice | Retrieve company details directly by UID. |
| UID Webservice | Check whether a UID exists in the register. |
| UID Webservice | Check whether a Swiss VAT number is valid and active. |
| Zefix and UID Webservice | Combine company, registry, VAT, and optionally publication data into a report. |
The tools return registry data; they do not provide legal, financial, or compliance advice.
Related MCP server: mcp-server-zefix
Node.js and npm
Zefix API credentials for Zefix-backed tools
An MCP client that supports local stdio servers
Request Zefix API credentials from the Federal Office of Justice at zefix@bj.admin.ch. UID Public Services do not require credentials.
git clone https://github.com/whybothercoding/zefix-mcp-server.git
cd zefix-mcp-server
npm install
cp .env.example .envEdit .env and set ZEFIX_USERNAME and ZEFIX_PASSWORD:
ZEFIX_USERNAME=your_zefix_username
ZEFIX_PASSWORD=your_zefix_passwordThe .env file is excluded from Git. Keep credentials out of source files and never commit them.
Optional settings:
Variable | Default | Description |
|
| Zefix REST API base URL. |
|
| UID Public Services WSDL. |
|
| Set to |
|
| Default cache lifetime in seconds; some API methods use their own TTL. |
|
| Pino log level: |
Use absolute paths in your MCP configuration. For direct local runs, start the process from the repository root so it loads .env. For MCP clients, pass the Zefix credentials through the client configuration as shown below, or use a local wrapper that loads your environment.
Add this server to your Claude Code MCP configuration. Replace the path with your local path:
{
"mcpServers": {
"zefix": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/zefix-mcp-server/src/index.js"],
"env": {
"ZEFIX_USERNAME": "${ZEFIX_USERNAME}",
"ZEFIX_PASSWORD": "${ZEFIX_PASSWORD}"
}
}
}
}Add this entry to ~/.codex/config.toml. Replace the path with your local path:
[mcp_servers.zefix]
enabled = true
command = "node"
args = ["/absolute/path/to/zefix-mcp-server/src/index.js"]
cwd = "/absolute/path/to/zefix-mcp-server"The cwd setting lets the server load credentials from .env in the repository. Alternatively, remove cwd and add env_vars = ["ZEFIX_USERNAME", "ZEFIX_PASSWORD"] to forward variables already present in the environment that launched Codex. In Codex TOML, env values are literal strings; ${VARIABLE} is not expanded.
Restart the MCP client after saving its configuration. The server communicates over stdio, so run it through the MCP client rather than as a standalone interactive command.
All inputs are JSON objects. UID and VAT numbers use the format CHE-123.456.789 (spaces and unformatted digits are also accepted by the server). Results are returned as text content, usually containing JSON; generate_due_diligence_report returns a Markdown report and raw JSON data.
search_companiesSearch Zefix by name. Names match by prefix; start the name with * for a contains-style match. Broad wildcard searches can be rejected by Zefix, so narrow them with a canton or legal form.
{
"name": "Migros",
"canton": "ZH",
"activeOnly": true,
"maxResults": 10
}name is required and must contain at least three characters. Optional inputs: canton, legalFormUid (for example, 0106 for an AG), activeOnly (default true), and maxResults (default 30, maximum 200). maxResults limits returned results; it does not reduce the number of matches Zefix evaluates.
get_company_by_uidRetrieve a company's Zefix record. uid is required. enrichWithUidData defaults to true; set it to false for a Zefix-only lookup. Publication text is returned separately by get_company_publications.
{
"uid": "CHE-106.052.527",
"enrichWithUidData": true
}advanced_searchSearch the UID Webservice. Provide at least one criterion: organisationName, personName, canton, or legalForms. personName takes officialName (required) and optional firstName. Other optional inputs are activeOnly (default true) and maxResults (default 30, maximum 200).
{
"organisationName": "Novartis",
"canton": "BS",
"legalForms": ["0106"],
"maxResults": 10
}get_company_details_uid, validate_uid, and validate_vat_numberEach takes one identifier:
{"uid": "CHE-106.052.527"}For VAT validation, use the company's VAT UID, which can differ from its company UID:
{"vatNumber": "CHE-116.268.023"}get_company_publicationsRetrieve a company's SOGC publications, newest first. Inputs: required uid; optional maxResults (default 20, maximum 200) and offset (default 0).
{
"uid": "CHE-106.052.527",
"maxResults": 10,
"offset": 0
}get_daily_registrationsRetrieve compact SOGC publication summaries for a date. Inputs: required date in YYYY-MM-DD format; optional canton, mutationType, maxResults (default 50, maximum 200), offset (default 0), and includeText (default false). A day may contain around 1,000 publications; filter before paging. mutationType accepts keys such as status.neu, status.loeschung, adressaenderung, and aenderungorgane; a parent key such as status matches its subtypes. Full publication text can be large, so keep pages small when includeText is enabled.
{
"date": "2026-09-29",
"canton": "ZH",
"mutationType": "status.neu",
"maxResults": 20
}generate_due_diligence_reportCombine Zefix and UID data for a company. uid is required. includePublications defaults to true; set it to false to omit publication data.
{
"uid": "CHE-106.052.527",
"includePublications": false
}The UID Webservice's public functions are limited to 20 requests per minute; exceeding the limit can temporarily block the caller. Avoid bursts and keep batch lookups below that ceiling. See the official UID Webservice information.
The Zefix REST API requires authentication and can return 429 when requests are throttled. The server retries selected transient HTTP errors, including 429, up to three times. Use specific searches, page through publication results, and avoid unnecessary concurrent calls. The Zefix REST API documentation describes the available endpoints.
Caching is disabled by default. When enabled with CACHE_ENABLED=true, responses are cached in memory for the lifetime configured by the method or CACHE_TTL. The cache is per server process and clears when the process restarts.
npm test
npm run lintThe tests use mocked API responses and do not require live Zefix credentials. To run the MCP server directly during development:
npm startThe process speaks MCP over stdio; starting it directly is mainly useful for client integration and diagnostics.
Zefix Public REST API — Swiss commercial register data and SOGC publications. API credentials are required.
UID Webservice — Swiss UID register public services, including UID and VAT validation. No authentication is required for the public services.
Zefix API access: zefix@bj.admin.ch
UID Webservice: uid@bfs.admin.ch
Server bugs and feature requests: GitHub Issues
MIT. Copyright (c) 2026 IndieGoWeb Ltd and (c) 2025 ishumilin. See LICENSE.
Advanced company search using the UID Webservice. Supports multiple filters including person names, legal forms, and canton.
| Name | Required | Description | Default |
|---|---|---|---|
| canton | No | Canton code (e.g., ZH, BE) | |
| activeOnly | No | Only return active companies | |
| legalForms | No | Array of legal form codes to filter by | |
| maxResults | No | Maximum number of results | |
| personName | No | Search by person name (for sole proprietorships) | |
| organisationName | No | Organization name (minimum 3 characters) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose read-only vs. mutating behavior (though search implies a read), return format, pagination, result caps, or any permissions. The mention of 'UID Webservice' is a marginal backend hint but adds little operational value.
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 concise sentences; the purpose is front-loaded before the filter enumeration. No wasted words, though the second sentence is largely a restatement of schema content.
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?
Six parameters, a nested personName object, and zero annotations for a search tool that competes with a sibling. The description omits how this differs from search_companies, what results look like, and any combination/AND semantics of the filters. Given the complexity and annotation gap, it is under-specified.
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 schema already documents every parameter with patterns, defaults, and constraints. The description restates three filter categories (person names, legal forms, canton) without adding syntax, format, or interaction details beyond the schema. 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: 'Advanced company search.' It distinguishes itself from the sibling search_companies by the 'advanced' qualifier and hints at filter richness. It doesn't explicitly say how it differs from search_companies, but the purpose is unambiguous.
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?
No when-to-use, when-not-to-use, or alternative routing is given. There is a sibling search_companies that likely overlaps, yet the description offers no guidance on when to pick this tool over that one. Usage is only implied by the word 'advanced.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a due diligence report for a Swiss company using Zefix and UID Webservice data.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Company UID in format CHE-XXX.XXX.XXX | |
| includePublications | No | Include recent SOGC publications in report (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral load. It mentions external data sources (Zefix, UID Webservice) but omits whether the operation is read-only, what permissions are required, how long it takes, or what form the report takes (download, email, inline).
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?
A single sentence, front-loaded with the core action and resource. No filler or 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?
No annotations and no output schema means the description should explain the report's contents and return behavior more fully. It gives only the data sources used, leaving the agent without essential context for invoking 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 coverage is 100%, so the two parameters are fully documented in the schema. The description adds no additional syntax or default behavior beyond what the schema already provides, which is the baseline for high coverage.
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 ('Generate') and resource ('due diligence report') for a Swiss company using named data sources. It does not explicitly differentiate from siblings like get_company_details_uid, but the report-generation intent is distinct.
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?
No guidance on when to use this tool versus alternatives such as get_company_details_uid or search_companies. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed company information from Zefix by UID. Optionally enriches data with UID Webservice information.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Company UID in format CHE-XXX.XXX.XXX | |
| enrichWithUidData | No | Enrich with additional data from UID Webservice (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does reveal that enrichment pulls from an external UID Webservice (useful latency/dependency context), but says nothing about authentication, rate limits, failure modes, or what 'detailed' information is returned.
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 short sentences, front-loaded with the core action and with no filler. Slightly terse given the tool's ambiguity relative to siblings, but structurally sound.
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 and no annotations, the description should describe the shape of the returned company data and any external-service caveats. It covers the enrichment dependency but leaves the agent without enough to know what it will receive or when this beats its sibling.
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 uid format and the enrichWithUidData default are already documented in the schema. The description only restates the enrichment option, adding no syntax or behavioral detail beyond the structured fields. 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?
The description states a specific verb and resource (get detailed company information) and the data source (Zefix), which is clear on its own. However, it does nothing to distinguish itself from the near-identical sibling get_company_details_uid, so it falls short of a 5.
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?
There is no when-to-use guidance, no prerequisites, and no mention of the far more obvious alternative get_company_details_uid. The agent is left to guess which of two nearly identically named lookup tools to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed company information using only the UID Webservice. This does not require Zefix authentication.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Company UID in format CHE-XXX.XXX.XXX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that no Zefix authentication is required and that the UID Webservice is used exclusively, but it omits other relevant traits such as return format, rate limits, or exactly what 'detailed company information' encompasses.
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 two efficient sentences, front-loaded with the core purpose followed by the auth constraint. Every sentence earns its place, though the data-source phrasing is slightly technical.
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 simple single-parameter read operation with a fully described schema, the definition covers purpose and authentication adequately. However, with no output schema, it could help by clarifying the scope of 'detailed company information' (e.g., which fields or sections are returned).
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 a single well-documented 'uid' parameter (format and pattern). The description adds no parameter meaning beyond what the schema already provides, so the baseline score 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?
The description states a clear verb+resource ('Get detailed company information') and adds the data-source qualifier ('using only the UID Webservice'). This is more specific than a generic lookup, but it does not explicitly differentiate from the similarly named sibling 'get_company_by_uid' or explain why one should be preferred.
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 statement 'This does not require Zefix authentication' implicitly suggests a usage condition (choose this when Zefix credentials are unavailable), but it does not state when to use versus alternatives or provide explicit exclusions. Guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get SOGC publications for a specific company by UID using the Zefix API, most recent first; page with maxResults and offset.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Company UID in format CHE-XXX.XXX.XXX | |
| offset | No | Number of publications to skip, for paging (default: 0) | |
| maxResults | No | Maximum number of publications to return, most recent first (default: 20, max: 200) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose useful behavior — results ordered most recent first, paging via maxResults/offset, source is the Zefix API — but says nothing about read-only nature, return shape, or rate limits.
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?
A single tightly-packed sentence front-loads the core action and appends the paging/ordering detail with no wasted 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 simple three-parameter read tool with full schema coverage, the description covers action, scope, ordering, and paging. With no output schema, the return contents are only named ('SOGC publications') rather than characterized, which is a minor 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?
Schema coverage is 100%, so all three parameters (uid, offset, maxResults) are already fully documented in the schema with formats, defaults, and limits. The description only reiterates that paging uses these two params, adding no syntax beyond 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 ('Get'), resource ('SOGC publications'), and scope ('for a specific company by UID'). The resource is distinct from siblings like get_company_details_uid or get_daily_registrations, though it doesn't explicitly name an alternative.
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?
Usage is only implied: an agent can infer this retrieves publications for a known UID, but there is no when-to-use/when-not guidance or routing to siblings such as get_company_details_uid or advanced_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get company registrations and publications from SOGC (Swiss Official Gazette of Commerce) for a specific date using the Zefix API. A day has ~1,000 publications, so results are compact summaries; filter by canton and mutationType, page with offset, and set includeText for the full publication text.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in format YYYY-MM-DD | |
| canton | No | Only publications of this cantonal commercial registry (2-letter code, e.g. ZH) | |
| offset | No | Number of matching publications to skip, for paging (default: 0) | |
| maxResults | No | Maximum number of publications to return (default: 50, max: 200) | |
| includeText | No | Include the full publication text (default: false; keep maxResults small when true) | |
| mutationType | No | Only publications with this mutation type key, e.g. status.neu (new registration), status.loeschung (deletion), status.aufl (dissolution), adressaenderung, firmenaenderung (name change), kapitalaenderung, aenderungorgane (officers). A key also matches its sub-keys (status matches status.*). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers substantial behavioral context: volume (~1,000 publications/day), that results are compact summaries by default, that includeText expands them, and the pagination model. It omits auth requirements and rate limits, so not 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?
Two dense sentences, front-loaded with the verb/resource/scope before the operational hints. Every clause (sources, volume, filters, paging, text flag) earns its place with 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?
For a 6-parameter read tool with no output schema and no annotations, the description covers volume expectations, default result shape, pagination, and the text toggle. It stops short of describing what the compact summary actually contains or how to page to exhaustion.
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 a cross-parameter interaction the schema does not encode: keeping maxResults small when includeText is true. That extra guidance raises it above the schema-duplication baseline.
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 company registrations and publications), names the source (SOGC via the Zefix API), and scopes it to a specific date. The date-scoping distinguishes it from the per-company sibling get_company_publications without needing to open either 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 clear operational context: filter by canton and mutationType, page with offset, and set includeText for full text. It does not explicitly state when to prefer this over siblings like get_company_publications or advanced_search, so it falls short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Swiss companies using the Zefix API. Supports filtering by name, canton, legal form, and active status. Names match by prefix; start with * to match anywhere. Zefix rejects searches that match too many companies (e.g. ab), so add canton or legalFormUid or use a more specific name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Company name to search for (minimum 3 characters, use * for wildcard) | |
| canton | No | 2-letter canton code (e.g., ZH, BE, GE) | |
| activeOnly | No | Only return active companies; excludes companies in liquidation or deleted (default: true) | |
| maxResults | No | Maximum number of results to return (default: 30, max: 200) | |
| legalFormUid | No | Legal form code (e.g., 0106 for AG, 0107 for GmbH) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full behavioral burden, and it discloses a real failure mode: Zefix rejects searches matching too many companies. It stops short of 5 because it says nothing about result ordering, rate limits, or the fact that this is a non-mutating read with no side effects.
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?
Four tight sentences: purpose first, then capability, then matching semantics, then the failure-mode remedy. Every sentence earns its place and nothing is repeated from the schema.
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 search tool with no annotations and no output schema, it covers purpose, filtering capability, and the main failure mode well. It is slightly incomplete in not indicating what the results contain or that they can chain into get_company_details_uid for the full record.
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 real semantics the schema only hints at: prefix-by-default matching and '*' meaning match-anywhere, plus the practical workaround of combining filters. It does not restate the canton/legalFormUid formats, which the schema already covers.
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 states a specific verb+resource ('Search for Swiss companies') and names the backing data source (Zefix API). It is clear, but it never distinguishes itself from the sibling 'advanced_search', which an agent must choose between, so it stops short of a 5.
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 gives concrete operating guidance: names match by prefix, '*' matches anywhere, and if Zefix rejects an over-broad search the agent should add canton, legalFormUid, or narrow the name. That is genuinely actionable context, but it offers no explicit when-to-use/when-not versus the sibling search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a Swiss UID (Unternehmens-Identifikationsnummer) using the UID Webservice. Checks if the UID exists in the official register.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | UID to validate in format CHE-XXX.XXX.XXX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden; it does disclose that the check is performed against an external UID Webservice and the official register, which is meaningful context. However it does not say what the response distinguishes (exists vs. doesn't exist), whether the call is network-dependent, or any error/rate-limit 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?
Two short sentences, front-loaded with the verb and resource, with the second sentence adding the lookup target. Nothing is wasted, though it is thin rather than maximally informative.
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 and no annotations, so the description is the only source for return semantics; it hints at a yes/no existence check but never states the result shape or failure modes. For a single well-specified parameter this is adequate but leaves a real gap around what the caller gets back.
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 the single uid parameter is fully documented with its CHE-XXX.XXX.XXX pattern, so the schema already does the work. The description adds no format or normalization detail beyond it, matching the baseline 3.
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 (validate) and resource (Swiss UID) and adds the mechanism (UID Webservice) plus the effect (checks existence in the official register). It is clearly distinguishable from siblings like get_company_by_uid or validate_vat_number, though it never names those alternatives explicitly.
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 the tool is for validating/verifying a UID but gives no when-to-use guidance, no prerequisites, and no exclusions versus siblings such as validate_vat_number or get_company_by_uid. The agent must infer the routing decision entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a Swiss VAT (MWST) number using the UID Webservice. Checks if the VAT number is valid and currently active.
| Name | Required | Description | Default |
|---|---|---|---|
| vatNumber | Yes | VAT number to validate in format CHE-XXX.XXX.XXX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose that validation goes through an external UID Webservice and that the result reflects current active status rather than mere format validity, which is useful. However, it says nothing about network/rate-limit behavior, failure modes, or permissions.
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 tight sentences with the core action and the validation scope front-loaded; nothing is redundant or padded.
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 lookup with no output schema, the description covers the essential behavior. The one gap is that it doesn't convey the shape of the result (boolean validity vs. structured status/details), which an agent must infer.
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 the single parameter is fully documented with a regex pattern and example format. The description adds no syntax or edge-case detail beyond the schema, 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 (validate) and resource (Swiss VAT/MWST number) and names the backing service (UID Webservice), so the agent knows exactly what it does. It does not explicitly differentiate itself from the sibling validate_uid, which is the main thing keeping it from a 5.
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?
There is no when-to-use guidance, no mention of when to prefer validate_uid versus this tool, and no statement of what to do with a negative result. Usage is only implied by the wording 'checks if valid and currently active'.
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.
v1.0.0advanced_searchgenerate_due_diligence_reportget_company_by_uidget_company_details_uidget_company_publicationsget_daily_registrationssearch_companiesvalidate_uidvalidate_vat_numberScored across 9 tools
Most tools have distinct purposes: validation of UID vs VAT, daily vs company publications, and Zefix vs UID Webservice detail lookups. However, search_companies and advanced_search overlap in company search, and get_company_by_uid and get_company_details_uid both retrieve company details from different sources, which could cause some selection hesitation.
The set mostly follows a snake_case verb_noun pattern such as validate_uid, get_company_by_uid, and generate_due_diligence_report. The main deviation is advanced_search, which is adjective_noun rather than verb-first, and get_company_details_uid puts the source qualifier after the noun.
Nine tools is well-scoped for a Swiss company registry and validation server. Each tool covers a distinct data source or operation area without excessive surface area.
The server covers the full read-only lifecycle: UID and VAT validation, company search and advanced search, company details via both Zefix and UID Webservice, daily and company-specific publications, and a due diligence report. No obvious operational gaps exist for the stated registry lookup domain.
Search and verify Swiss companies, UID status and register changes with dated official sources.
Swiss bankruptcy, liquidation and register alerts for a UID list. Source: SHAB. Webhook, API, email.
Swiss business verification with per-check source provenance and evidence freshness.
Swiss commercial register: companies, officers, bankruptcy risk, and your monitored lists.