Apier MCP Server

Search companies by name

search_companies

Read-onlyIdempotent

Resolve a Norwegian company name to its 9-digit organisasjonsnummer so you can proceed with company lookups. Searches Brønnøysund's register and returns up to ten candidate matches.

Instructions

Resolve a Norwegian company NAME to its 9-digit organisasjonsnummer. Use this as your FIRST call whenever you have a company's name but NOT its org_number — every other company tool requires the 9-digit number, and guessing a MOD-11-valid number risks hitting the wrong company. Searches Brønnøysund's public Enhetsregisteret and returns a token-efficient candidate list: up to ten matches, five fields each (name, org_number, org_form, municipality, registry status). Then call get_company_summary or get_company_context with the chosen org_number (skip a deleted or bankrupt match unless you meant it). Input: { name } (2–100 chars, æ/ø/å supported). On NOT_FOUND, broaden the name and drop the legal form — never loop on the same name. Failure modes: VALIDATION_FAILED, NOT_FOUND, SCOPE_INSUFFICIENT (needs read:brreg), UPSTREAM_TIMEOUT / UPSTREAM_UNAVAILABLE. No sandbox mirror — the sandbox fixtures catalog already lists every synthetic org. Docs: https://www.apier.no/docs/guides/norwegian-company-register-search

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes	Company name to search for (2–100 characters, trimmed). Free-text; matched against Brønnøysund's registered `navn` field. Omit the legal form for a broader match (search `Nordic Widgets`, not `Nordic Widgets AS`) — a too-specific or misspelled name returns a NOT_FOUND you must broaden. Norwegian characters (æ/ø/å) are supported.

Output Schema

TableJSON Schema

Name	Required	Description
`_meta`	No
`result`	Yes	The /company/search projection: { query, count, candidates } — five fields per candidate (name, org_number, org_form, municipality, status). Pick an org_number, then call get_company_summary / get_company_context.
`metadata`	Yes
`justification`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.1Sep 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable complementary detail: it returns a token-efficient candidate list of up to ten matches with five fields each, lists specific failure modes including the required scope (read:brreg), and discloses that there is no sandbox mirror. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

The description is front-loaded with the core purpose and first-step guidance, then moves through result shape, follow-up actions, error recovery, failure modes, and sandbox behavior. It is dense but every sentence earns its place, with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only search tool with an output schema, this description is complete. It covers when to call it, what results look like, what to do next, how to recover from NOT_FOUND, which failure modes to expect, and how sandbox behavior differs. An agent has everything needed to invoke it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema's name parameter already documents length, trimming, free-text matching, legal-form omission, and NOT_FOUND broadening. The description mostly restates these constraints or gives usage advice rather than adding new parameter-level meaning, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it resolves a Norwegian company name to its 9-digit organisasjonsnummer by searching Brønnøysund's public Enhetsregisteret. It also clearly distinguishes itself from sibling tools by explaining that every other company tool requires the org_number, making this the necessary first lookup step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

The description explicitly says to use this as the FIRST call whenever you have a name but not an org_number. It names the follow-up tools (get_company_summary, get_company_context), tells the agent to skip deleted or bankrupt matches unless intended, and gives concrete NOT_FOUND handling: broaden the name and drop the legal form rather than retrying the same input.

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