Company lookup

Look up a company

lookup_company

Read-onlyIdempotent

Look up a company by legal name, or check an EU VAT id. When tax_id is set, VIES is the only source and the row has vies_valid true or false. error vies_unavailable means VIES did not answer and the call is not charged. error bad_tax_id means the number is not an EU VAT id and the call is not charged. Without tax_id, query searches GLEIF by legal name. An empty companies list means no LEI record and still costs 0.05 credit. error gleif_unavailable is not charged. No sample company is ever returned. Key: https://firm.bestsmartgoods.com/signup

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "lookup_company"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Maximum matches to return. Default 5. Values outside 1 to 20 are clamped.
`query`	No	Legal name for a GLEIF search. Required when tax_id is omitted. Ignored when tax_id is set.
`tax_id`	No	EU VAT number. When set, the answer is only the VIES check. A leading country code is used when present.
`country`	No	Two-letter ISO code, for example HU. Narrows a name search. Used as the VAT country when tax_id has no leading country code. Defaults to HU for a tax id.

Output Schema

Name	Required	Description	Default
`companies`	Yes	Matches, already limited. Empty when nothing matched.
`credits_remaining`	Yes	Balance after this successful call.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedNov 5, 2026

changedInput schema / properties / country / description

Previous value: -"Two-letter ISO code, for example HU. Omit it to search every country."New value: +"Two-letter ISO code, for example HU. Narrows a name search. Used as the VAT country when tax_id has no leading country code. Defaults to HU for a tax id."

changedInput schema / properties / query / description

Previous value: -"Legal name or registration number. A partial name can return several GLEIF matches, already cut to limit."New value: +"Legal name for a GLEIF search. Required when tax_id is omitted. Ignored when tax_id is set."

changedInput schema / properties / tax_id / description

Previous value: -"EU VAT number, checked on VIES in addition to the name search. A leading country code is used when present; otherwise country is used, defaulting to HU."New value: +"EU VAT number. When set, the answer is only the VIES check. A leading country code is used when present."

changedInput schema / required

Previous value: -[
-  "query"
-]New value: +[]

changedOutput schema / properties / companies / items / properties / confidence / description

Previous value: -"0.9 for VIES, 0.8 for GLEIF, 0.5 for demo."New value: +"0.9 for VIES, 0.8 for GLEIF."

changedOutput schema / properties / companies / items / properties / source / description

Previous value: -"demo is a fixture used only when the live sources returned nothing."New value: +"gleif for a name search, vies for a VAT check."

changedOutput schema / properties / companies / items / properties / source / enum

Previous value: -[
-  "gleif",
-  "vies",
-  "demo"
-]New value: +[
+  "gleif",
+  "vies"
+]

Changed8 schema fields changedNov 3, 2026

changedInput schema / properties / country / description

Previous value: -"ISO country code, for example HU."New value: +"Two-letter ISO code, for example HU. Omit it to search every country."

addedInput schema / properties / limit / default
```
Added value: +5
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of matches to return."New value: +"Maximum matches to return. Default 5. Values outside 1 to 20 are clamped."

addedInput schema / properties / limit / maximum
```
Added value: +20
```
addedInput schema / properties / limit / minimum
```
Added value: +1
```

changedInput schema / properties / query / description

Previous value: -"Company name, registration number, or tax id."New value: +"Legal name or registration number. A partial name can return several GLEIF matches, already cut to limit."

changedInput schema / properties / tax_id / description

Previous value: -"Tax id when it is known separately from the query."New value: +"EU VAT number, checked on VIES in addition to the name search. A leading country code is used when present; otherwise country is used, defaulting to HU."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "companies": {
+      "description": "Matches, already limited. Empty when nothing matched.",
+      "items": {
+        "properties": {
+          "address": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "company_number": {
+            "description": "Registration number when the source provides one.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "confidence": {
+            "description": "0.9 for VIES, 0.8 for GLEIF, 0.5 for demo.",
+            "type": "number"
+          },
+          "country": {
+            "description": "ISO country code.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "lei": {
+            "description": "GLEIF LEI when source is gleif.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "name": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source": {
+            "description": "demo is a fixture used only when the live sources returned nothing.",
+            "enum": [
+              "gleif",
+              "vies",
+              "demo"
+            ],
+            "type": "string"
+          },
+          "status": {
+            "description": "Registry status, or vat_valid or vat_invalid for VIES.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "tax_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "vies_valid": {
+            "description": "Present only on a VIES row.",
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "credits_remaining": {
+      "description": "Balance after this successful call.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "credits_remaining",
+    "companies"
+  ],
+  "type": "object"
+}

First observedNov 3, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses the cost model (0.05 credit per call, empty result still charged), which failures are not charged (vies_unavailable, bad_tax_id, gleif_unavailable), that no sample company is ever returned, and that VIES is the sole source when tax_id is set. This is exactly the kind of billing and failure semantics an agent cannot infer from structured fields.

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

Conciseness4/5

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

Front-loads the two operating modes, then the error and cost semantics in compact sentences. The telegraphic 'error X means Y' phrasing is efficient, though the trailing signup URL is promotional rather than operational and slightly dilutes the structure.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description still covers the key row field (vies_valid), all failure modes, and the credit cost. For a two-mode lookup tool, nothing an agent needs in order to call it correctly is missing.

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 coverage is 100%, so limit clamping, query/tax_id precedence, and the country default are already documented in the schema. The description restates the tax_id-versus-query precedence and the HU default but adds no format or syntax detail beyond what the schema provides, so the baseline of 3 applies.

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?

States a specific verb and resource and explicitly splits the tool into two modes: a GLEIF legal-name search and a VIES EU VAT check. An agent immediately knows what the tool returns and which input selects which mode, with no sibling tools to confuse it.

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?

Gives explicit routing rules: set tax_id for the VIES-only check, omit it and supply query for the GLEIF name search, and note that query is ignored when tax_id is set. There are no alternative tools, so the mode-selection guidance is the complete usage decision.

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

All Company lookup tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.