An MCP server for Swiss company data. Nine tools that look a company up by UID, search 790,000 of them by name or by statutory purpose, trace what changed in the commercial register, browse public tenders, check a bank licence, resolve a UID to an LEI and its group parent, and find federally funded research a company took part in.
claude mcp add swissco -- uvx swissco-mcpAll data comes from six open-data sources, none of which needs a credential: Zefix on LINDAS for the commercial register, the Amtsblattportal for the Swiss Official Gazette of Commerce, simap.ch for public procurement, FINMA for authorised banks and securities firms, GLEIF for the Legal Entity Identifier and group structure, and ARAMIS for federally funded research.
Built and maintained by Prospex, a Swiss B2B sales intelligence platform.
The server runs over stdio and needs Python 3.14 or newer.
uvx swissco-mcp # run it without installing
pip install swissco-mcp # or install itRegistering it depends on the host. Claude Code takes one command:
claude mcp add swissco -- uvx swissco-mcpAnything that reads a JSON config takes the equivalent block:
{
"mcpServers": {
"swissco": {
"command": "uvx",
"args": ["swissco-mcp"]
}
}
}Related MCP server: mcp-swiss
Tool | What it answers |
| Everything the register publishes about one company, optionally with its FINMA licence and its LEI |
| Companies whose legal name or statutory purpose contains a term |
| Commercial-register publications from the gazette in a date range |
| One company's registry events, each confirmed against the publication's own UID |
| Public-procurement projects published on simap |
| Whether a company holds a simap vendor profile, and what it says |
| Institutions on FINMA's list of authorised banks and securities firms |
| A company's LEI, the entity that consolidates it, and the entity at the top of that chain |
| Federally funded research projects, Innosuisse and SNSF money included |
Every tool returns the same envelope: rows, a count, and notes.
Each source covers a slice of Swiss economic life, and a company's absence from
one of them usually means it sits outside that slice. notes says which:
FINMA's list covers banks and securities firms. Insurers, portfolio managers and fund management companies hold their authorisations on other lists, so a company missing here may still be supervised.
About 28,000 Swiss entities hold an LEI, against roughly 790,000 in the commercial register. An absent LEI is the normal case.
ARAMIS searches project titles, abstracts and a free-text contractor field, and indexes the structured participant list under none of them. A company named only as a structured partner cannot be found through it.
LINDAS publishes the active commercial register. A deleted company can be missing from it while its gazette publications remain.
notes also reports what a call did with a request it had to trim, and how many
requests a wide date range is about to cost.
Every tool works with no configuration at all. Four environment variables change what it does:
Variable | Effect |
| Zefix PublicREST credentials, issued by |
| Where gazette bodies and the two FINMA files are cached. Defaults to |
| Seconds between requests. It can raise the floor of 0.5s and cannot lower it |
Requests are paced at half a second apart, and each source that asks for
something slower gets it: FINMA is paced at a second. These are small public
services run by federal offices, and SWISSCO_INTERVAL can raise that floor
but never lower it.
The same data is available as a shell command, from the same repository:
uvx swissco lookup CHE-444.420.929See swissco on PyPI and its documentation.
Full reference for every tool, its arguments and its caveats: swissco-mcp.readthedocs.io.
MIT. The data belongs to its publishers, and each source's own terms apply; the access and terms section lists them.
One company's registry events, each confirmed against the publication's own UID.
Each row carries publication_date, event_type,
effective_date, company_name, uid, canton,
sub_rubric, id and url, newest first.
The gazette's list page carries a title and no UID, so the UID resolves to a legal name, the name selects candidate publications, and each candidate's body is fetched and kept only when its own UID matches. A publication carrying no UID is dropped.
Bodies are cached under the state directory and keyed by publication id, so an overlapping second call over the same range costs almost nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | The company's UID. | |
| limit | No | Maximum rows. | |
| since | No | First publication date, YYYY-MM-DD. Defaults to a year ago. | |
| until | No | Last publication date, YYYY-MM-DD. Defaults to today. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent, but the description adds genuinely new behavioral context: publications carrying no UID are dropped, and bodies are cached in the state directory keyed by publication id so overlapping calls are cheap. These are real operational traits not derivable from structured fields. It stops short of describing error/failure behavior when a UID resolves to nothing.
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 in the first sentence, followed by the row shape and the resolution/caching mechanics. The enumerated row fields and double-backtick formatting are somewhat verbose given an output schema exists, but ordering info ("newest first") and the caching note earn their 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?
With an output schema present the return shape needn't be repeated, and annotations cover the safety profile; the description still supplies the resolution pipeline, the drop-on-missing-UID rule, and caching. Nothing an agent needs in order to call this 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?
Schema coverage is 100%, so uid/limit/since/until are already documented with types, defaults, and date formats. The description adds nothing about parameter syntax or interaction (e.g., how limit interacts with since/until windows). Baseline 3 is appropriate when the schema carries the parameter burden.
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+resource: returns "one company's registry events" from gazette publications, with the confirmation-vs-UID qualifier adding precision. An agent can tell it is a per-company event reader. However, it never distinguishes itself from adjacent siblings like swissco_publications or swissco_search, leaving the boundary implicit.
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: the required uid parameter and the "one company's" framing suggest it is the right call when you already have a company UID. There is no explicit when-to-use/when-not guidance and no routing to swissco_lookup (for getting the UID) or the other publication-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Institutions on FINMA's list of authorised banks and securities firms.
Each row carries name, city, licence_type,
supervisory_category, uid, foreign_control,
no_securities_firm_activity,
non_account_holding_securities_firm and
about_to_cease_operations.
This one list covers banks and securities firms. Insurers, portfolio managers and fund management companies hold their authorisations on other FINMA lists, so a company absent here may still be supervised. FINMA also publishes some authorised institutions with no UID, which no UID lookup can reach.
Both published files are cached under the state directory for a day, so the first call in a day is the slow one.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | No | One institution by UID. | |
| limit | No | Maximum rows. | |
| query | No | Text to match in the institution's name or city. | |
| category | No | FINMA supervisory category, 1 to 5. 1 is the largest. | |
| licence_type | No | Bank, Securities firm, Foreign bank branch office, or Foreign securities firm branch office. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/openWorld/idempotent, so the bar is lower, and the description still adds genuinely useful operational context: both files are cached for a day and the first call of the day is slow, and some institutions carry no UID and cannot be reached by UID lookup. This is real behavior beyond 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 each section (fields, scope, caveats, caching) is a distinct, non-redundant block. The medium-length field enumeration partially duplicates the output schema, which keeps it from a full 5.
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, return values need not be explained, and the description still supplies scope limits, the no-UID gap, and caching latency. It is complete enough for an agent to call correctly; the only omission is any routing pointer to a sibling for the excluded institution types.
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 schema already documents uid, limit, query, category and licence_type. The description adds no new parameter meaning (the licence-type examples live in the schema), so the 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 first sentence names a specific resource (FINMA's list of authorised banks and securities firms) and the enumerated row fields make the scope concrete. It is distinguishable from data-source siblings like swissco_lei, but it never names an alternative, so it stops short of 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 clearly states the boundary condition: this list covers banks and securities firms only, while insurers, portfolio managers and fund managers are on other FINMA lists, so absence here does not imply unsupervised. That is a strong 'when it applies and when it does not' signal, but no sibling tool is named as the alternative for the excluded cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A company's Legal Entity Identifier and the group it is consolidated into.
One row: legal_name, lei, registered_as, jurisdiction,
status, registration_status, legal_form, city,
country, other_names, bic, initial_registration_date,
last_update_date, next_renewal_date, direct_parent,
ultimate_parent and direct_children.
With children, one row per consolidated entity: legal_name,
lei, jurisdiction, registered_as, status, city and
country.
GLEIF Level 2 records accounting consolidation, so a parent here is the entity that consolidates this one into its accounts. That parent is frequently foreign, which is the case for reading it: the Swiss commercial register carries no entry for a Swiss company's owner abroad.
About 28,000 Swiss entities hold an LEI against roughly 790,000 in the commercial register. An absent LEI is the normal case.
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | The company's UID. | |
| limit | No | Maximum children. | |
| children | No | List the entities this one consolidates instead of counting them. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, openWorld), yet the description adds genuine domain behavior: GLEIF Level 2 records accounting consolidation, the listed parent is the accounting consolidator, that parent is frequently foreign and therefore absent from the Swiss register, and only ~28,000 of ~790,000 Swiss entities hold an LEI. This materially shapes how an agent should interpret results and empty responses.
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 mode-specific explanations earn their place. The verbatim column lists are the weakest part, since an output schema already exists and arguably documents those fields, but overall the structure is efficient and readable.
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 read-only lookup with full schema coverage, three annotations, and an output schema, the description supplies exactly the missing pieces: the data model behind the L2 consolidation fields and the expectation that most entities have no LEI. Nothing essential for correct invocation 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, but the description adds real meaning: it spells out what each mode returns and clarifies that ``children`` switches from counting to listing consolidated entities. The exact fields per mode go beyond the terse schema descriptions.
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 names a specific resource (a company's LEI and its consolidation group) and the two modes are clearly described (single row vs. one row per consolidated child). It does not, however, contrast itself with any sibling tool (e.g. swissco_lookup, swissco_search), so the agent must infer when this is the right call.
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 implied rather than stated: the description explains the semantics of the ``children`` mode and warns that 'an absent LEI is the normal case,' which primes correct interpretation of empty results. There is no explicit when-to-use/when-not or reference to alternative sibling tools for company data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything the commercial register publishes about one company.
One row: legal_name, uid, chid, ehra_id,
legal_form_code, legal_form, municipality, canton,
address, purpose and zefix_uri. With Zefix PublicREST
credentials in the environment it also carries status,
capital_nominal, capital_currency, deletion_date,
old_names, branch_offices, head_offices, has_taken_over,
was_taken_over_by and cantonal_excerpt.
finma_licence adds finma_licence, finma_category,
finma_city and finma_flags. lei adds lei, lei_status,
direct_parent and ultimate_parent.
purpose is the statutory purpose: how the company describes what it
does, in its own words, filed with the register.
| Name | Required | Description | Default |
|---|---|---|---|
| lei | No | Add the LEI and the entities that consolidate this one. Costs three requests. | |
| uid | Yes | A Swiss UID in any punctuation: CHE-444.420.929, CHE444420929, or a CH-ID. | |
| finma_licence | No | Add the FINMA licence type and supervisory category. Costs two downloads on a cold cache. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld, so safety profile is covered. The description adds genuinely useful behavioral context beyond them: output varies with Zefix PublicREST credentials present in the environment, and optional flags cost extra requests/downloads ('three requests', 'two downloads on a cold cache'). It stops short of describing error/not-found behavior or cache semantics.
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 core statement is front-loaded and efficient, but the long enumeration of every returned field largely duplicates the existing output schema, padding the description without adding decision-relevant information. The credential-conditional grouping is the only part of that list that 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 read-only lookup, the definition covers what an agent needs: the identifying key, the conditional output tiers based on credentials, and the cost of the optional flags. Because an output schema exists, the field list is not strictly required, and the only real omission is failure behavior when a uid is unknown.
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 baseline is 3. The description goes beyond the schema by mapping each optional flag to the concrete fields it unlocks (lei → lei, lei_status, direct_parent, ultimate_parent; finma_licence → finma_licence, finma_category, finma_city, finma_flags), which the schema's terse 'entities that consolidate this one' does not spell out.
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 names a specific action and resource: retrieving everything the commercial register publishes about one company (keyed by a required uid). This implicitly separates it from the multi-result sibling swissco_search, but no sibling is named explicitly, so differentiation requires inference.
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 implied by the access pattern (single uid in, one row out), and the description explains when the optional finma_licence/lei data is added. However, there is no explicit when-to-use guidance or routing against the eight sibling tools (e.g. when to prefer swissco_search or swissco_finma instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Commercial-register publications from the Swiss Official Gazette of Commerce.
Each row carries publication_date, canton, sub_rubric,
title, language, state, id and url. With
event_types, each body is fetched and parsed, and the rows instead
carry publication_date, canton, sub_rubric, company_name,
uid, events, effective_date, state, id and url.
The event types are: INCORPORATION, BRANCH_CREATED, SEAT_MOVED, ADDRESS_CHANGED, NAME_CHANGED, PURPOSE_CHANGED, CAPITAL_INCREASED, MERGER, OFFICERS_CHANGED, LIQUIDATION, DELETED.
The gazette publishes around a thousand commercial-register entries a day.
Every filter here is applied over the listed publications, because the
anonymous API ignores its own cantons, subRubrics and q
parameters.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows. | |
| query | No | Text to look for in the title, in any of the four languages. | |
| since | No | First publication date, YYYY-MM-DD. Defaults to yesterday. | |
| until | No | Last publication date, YYYY-MM-DD. Defaults to today. | |
| cantons | No | Canton codes to keep, e.g. ['ZH', 'ZG']. | |
| event_types | No | Keep only publications carrying one of these events. Each one costs a body fetch. | |
| sub_rubrics | No | HR01 registrations, HR02 mutations, HR03 deletions. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the description earns credit for going further: it discloses that event_types changes the row shape via body fetch, that the gazette publishes ~1000 entries/day, and that the upstream API ignores its own cantons/subRubrics/q parameters so filtering is done client-side. Only pagination/ordering behavior is left unstated.
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?
Well front-loaded with the purpose, but it spends two long paragraphs enumerating output fields that are already declared in the output schema, which is redundant structure rather than useful conciseness.
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 7-parameter, all-optional, open-world read tool with an existing output schema, this is essentially complete: cost model, output-shape variance, and the underlying API quirk are all covered. Only sequencing/ordering and rate-limit specifics are absent.
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 baseline is 3, but the description adds real meaning beyond the schema: it explains why the filters exist at all (the anonymous API ignores its own filter params), why event_types is expensive ('Each one costs a body fetch'), and how the parameter alters the returned columns.
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 resource ('Commercial-register publications from the Swiss Official Gazette of Commerce') and makes clear this is a filtered list/fetch over those publications. It does not name or differentiate itself from siblings like swissco_search or swissco_events, but the resource 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?
There is no explicit when-to-use guidance or routing to alternatives among the eight sibling tools. The only operational hint is implied – that event_types triggers body fetches – which is closer to a cost note than a usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Federally funded research projects from ARAMIS, Innosuisse and SNSF money included.
A text query returns rows of title, project_number, office,
status, start_date, end_date, granted_total_costs,
participants and aramis_id.
A UID searches ARAMIS for the company's name, then keeps only projects
carrying a participant whose own UID matches, and reports role and
uid in place of participants.
ARAMIS searches project titles, abstracts and the free-text contractor field, and indexes the structured participant list under none of them. A company named only as a structured partner cannot be found, which is where Innosuisse implementation partners usually sit. An empty result means no project mentions the company by name, and is not evidence that it took no federal research money.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows. | |
| query | Yes | A UID, which is confirmed against each project's participant UID, or text to search projects for. | |
| language | No | Service language: DE, EN, FR or IT. Case-sensitive. | EN |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, openWorld), but the description adds substantive behavior beyond them: the two distinct return shapes for text vs UID queries, the differing field sets (role/uid replacing participants), ARAMIS indexing limitations, and the critical false-negative caveat. No auth/rate-limit detail, but the search-scope disclosure is genuinely valuable.
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 content is front-loaded and organized into query-mode and limitation paragraphs, but the opening sentence is a fragment ('...money included.') and the full list of return fields is partly redundant given an output schema exists. Information density is good but there is trimming left on the table.
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 non-obvious bifurcated behavior, the description covers query semantics, the distinct result shapes, and the interpretation trap of empty results. With an output schema present, return-value enumeration is arguably redundant, and the description does not clarify the 'language' parameter's effect on search, leaving 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 the baseline is 3; the description earns an extra point by elaborating what the 'query' parameter actually does on each path (text vs UID resolution) beyond the schema's terse 'A UID ... or text to search projects for'. It does not add anything for limit or language, which the schema already documents.
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 establishes a specific resource (federally funded research projects from ARAMIS/Innosuisse/SNSF) and implies the retrieval action through its description of query behavior. However, it never explicitly frames itself as a search tool nor names a sibling (e.g. swissco_search) to distinguish scope, so an agent must infer the distinction from the data source.
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 usage context: a text query searches names, abstracts and contractor fields, while a UID triggers a two-step ARAMIS name lookup then participant-UID confirmation. It also adds a strong 'when-not' caveat (an empty result is not evidence of no funding). It stops short of explicitly routing to sibling tools for other resource types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Companies whose name or statutory purpose contains term.
Over LINDAS, each row carries legal_name, uid, legal_form,
municipality, canton and purpose. Over PublicREST:
legal_name, uid, chid, ehra_id, canton and status.
The purpose is what makes this worth running. It is how a company
describes its own business to the register, so "hydrogen storage" finds
companies whose name mentions neither word. via="rest" matches the
start of a name instead.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | lindas matches a substring of the name or the purpose; rest matches a name prefix and needs Zefix PublicREST credentials. | lindas |
| term | Yes | Text to look for in the legal name or the statutory purpose. | |
| limit | No | Maximum rows. | |
| canton | No | Two-letter canton code, e.g. VD. LINDAS only. | |
| legal_form | No | eCH-0097 legal-form code, e.g. 0106 for an AG. LINDAS only. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered. The description adds non-obvious behavior: substring matching on name OR purpose, prefix-only matching for rest, and the credential requirement for the rest backend — all context the annotations do not convey. It is silent on result ordering and pagination, but the matching semantics are the important disclosure here.
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 core purpose is front-loaded and the rationale follows cleanly. The mid-paragraph enumeration of returned fields per backend is largely duplicated by the output schema and is the weakest, least-earning part, but the rest is tight.
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, return fields need not be re-explained, and annotations cover safety, so the description is close to complete. The remaining gaps are minor: no explicit routing to sibling lookup tools and no mention of result ordering or volume limits.
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 term, via, limit, canton and legal_form. The description reinforces the via semantics and clarifies that the LINDAS match covers both name and purpose, but adds nothing about limit, canton or legal_form beyond what the schema states. Baseline 3 is appropriate when the schema does the heavy lifting.
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: find companies by matching *term* against legal name or statutory purpose. It also distinguishes the two backends (LINDAS vs PublicREST) and their returned fields, so the agent knows exactly what operation this is. It stops short of naming or contrasting any of the many siblings (swissco_lookup, swissco_lei, etc.), so an agent must infer boundary cases.
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 a concrete reason to prefer this tool ("the purpose is what makes this worth running") and explains the behavioral fork between backends: LINDAS matches a name/purpose substring, while via="rest" matches a name prefix. That is genuine when-to-use guidance. It does not state when NOT to use it or name an alternative sibling for entity-specific lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public-procurement projects published on simap.
Each row carries title, project_number, buyer, canton,
city, project_type, process_type, publication_date,
publication_type, project_id and publication_id.
The publication types are: abandonment, advance_notice, award, competition, direct_award, participant_selection, request_for_information, revocation, selective_offering_phase, study_contract, tender.
The date matches each project's newest publication, whichever type that
publication is, and pub_types is what narrows it to awards. The
supplier named on an award carries no UID, so this lists projects and
buyers. Use swissco_vendor for whether a given company is in simap's
vendor directory.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Preferred language for the title and buyer: de, fr, it or en. Defaults to de, then fr, it, en. | |
| limit | No | Maximum rows. | |
| since | No | First publication date, YYYY-MM-DD. Defaults to a week ago. | |
| until | No | Last publication date, YYYY-MM-DD. Defaults to today. | |
| cantons | No | Canton codes to keep, e.g. ['ZH', 'ZG']. | |
| pub_types | No | Publication types to keep, e.g. ['tender', 'award']. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, it discloses real behavior: the date filter matches each project's newest publication of any type, and that suppliers named on awards carry no UID so the tool returns projects and buyers only. It omits ordering, pagination, and rate-limit behavior, but the annotations already cover the safety profile.
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?
Front-loaded with the tool's purpose, then structured into field list, vocabulary, and semantics. The 11-field enumeration is partly redundant given an output schema exists, but the publication-type list is not available elsewhere in structured form, so most sentences earn their 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?
With an output schema, full parameter descriptions, and annotations present, the description only needed to add behavioral nuance — which it does via the newest-publication date semantics and the award/vendor caveats. Ordering and pagination behavior remain unspecified, a minor gap for a list 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?
Schema coverage is 100%, so the baseline is 3, and the description adds genuine meaning on top: it explains that since/until bind to the newest publication date per project and that pub_types is the lever for narrowing to awards. It even supplies the publication-type vocabulary that the schema leaves as a free string.
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 concrete resource (public-procurement projects from simap) and enumerates the row fields it returns, so the agent knows exactly what it gets. It explicitly carves out a boundary against swissco_vendor, though it does not distinguish itself from possibly-overlapping siblings like swissco_publications or swissco_search.
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 one explicit routing rule — use swissco_vendor to check whether a company is in simap's vendor directory — plus the condition that pub_types narrows results to awards. There is clear context but no broader when-not-to-use guidance relative to other simap-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A company in simap's vendor directory, by UID or by name.
A text query returns rows of name, uid_no, canton, city,
postal_code, active, is_bidding_consortium and vendor_id.
A UID resolves to a legal name, searches the directory for it and keeps
only profiles whose own uidNo matches, then returns that profile:
name, uid_no, additional_name, street, postal_code,
city, canton, url, company_size, type_of_services,
cpv_codes, bkp_codes, npk_codes, business_purpose,
is_bidding_consortium, leading_vendor_name and vendor_id.
A company can bid without holding a directory profile, and a bidding consortium carries no UID at all, so an absent UID means only that no profile is filed under it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows on the text path. | |
| query | Yes | A UID, which is confirmed exactly, or text to search vendor names for. |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| count | Yes | |
| notes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), but the description adds real behavioral context beyond them: text results are row-shaped and bounded by limit, UID results are exact-match filtered on uidNo, and — most valuable — an absent UID does not imply the company is absent from the directory (companies can bid without a profile, and consortia carry no UID). That caveat prevents a false-negative conclusion an agent could otherwise draw.
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 scoping sentence is front-loaded and the closing caveat is high-value, but the middle paragraphs exhaustively enumerate 9 and 18 return fields respectively — an output schema exists, so this field dump largely duplicates structured data and inflates the description.
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 dual-mode lookup with a schema and output schema in place, the description covers both resolution paths, their differing result shapes, and the key edge case about missing UIDs. Pagination beyond `limit` and any behavior for ambiguous name matches (zero or many hits) are the only material gaps.
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 genuinely adds meaning: it explains that the same `query` parameter is interpreted two different ways (exact-confirmed UID vs. name search) and that `limit` only applies on the text path, which is not inferable from the bare property descriptions.
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 names a specific resource (a company in simap's vendor directory) and the two lookup modes (UID or name), so the agent knows exactly what the tool retrieves. It does not, however, differentiate itself from siblings like swissco_lookup or swissco_search, several of which sound like plausible substitutes for a directory lookup.
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 does distinguish the two query modes — a text query returns a row list, a UID resolves to one profile — which is implicit guidance on how to call it. It gives no when-to-use guidance versus alternatives (swissco_lookup, swissco_search), no prerequisites, and no statement of when this tool is the wrong choice.
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.
v0.1.1swissco_eventsswissco_finmaswissco_leiswissco_lookupswissco_publicationsswissco_researchswissco_searchswissco_tendersswissco_vendorScored across 9 tools
Each tool maps to a distinct data source or action (register lookup, register search, gazette feed, company events, tenders, vendor directory, FINMA, LEI, research). The only real overlap is between swissco_publications (general gazette stream) and swissco_events (gazette events for one company), but the descriptions clearly distinguish the two scopes.
All tools share the swissco_ prefix and snake_case formatting, giving a predictable namespace. The suffix mixes action words (lookup, search) with data-source nouns (finma, lei, tenders, research), a minor inconsistency but still readable and non-ambiguous.
Nine tools is well-scoped for a multi-source Swiss company-data aggregator. Each tool covers a genuinely distinct source, so none feels redundant or padded.
The surface covers identities (lookup/search), registry activity (publications/events), public money (tenders/research), and supervision (finma/lei/vendor) — a strong lifecycle view. Minor gaps exist (e.g. no way to filter by canton or list all results), but agents can work around these with the provided filters.
Swiss customs (TARES), FINMA registry & NOGA/NACE/ISIC classifications. 9 MCP tools, free tier.
Search and verify Swiss companies, UID status and register changes with dated official sources.
CompanyLens is a remote MCP server giving AI agents instant access to official company registry data across 19 jurisdictions in Europe, the Americas, and Asia-Pacific. Eighteen read-only tools let you search companies and people, look up officers and beneficial owners, map corporate networks through shared directors, screen names against the UK disqualified directors register, find every company at a registered address, and pull filing history — all from a single connector. Visit our website: https://companylens.io
Hosted MCP server for real-world data: business registries, sanctions, companies, domains, crypto.
