Skip to main content
Glama

Find a company by NIF

company_by_nif
Read-onlyIdempotent

Look up a company by NIF/CIF. Use it for a tax ID; for names, search_companies. On a hit, call company_history with company_slug.

Returns {found, company_slug, current_name, website, lei, nif_caveat, ...}; use current_name. lei: GLEIF Legal Entity Identifier matched by NIF; null means no match yet. website: newest BORME website act; null if none or removed.

BORME has no dedicated tax-ID field: more than 580,000 NIF mappings from public sources and the text of BORME notices cover a minority of companies. reason nif_unmapped: not matched yet, not proof of absence. reason nif_revoked: AEAT records a revocation; relay tell_the_user. On a company match, relay nif_status.note if present. invalid_input true: not a NIF/CIF. reason nif_check_character_failed: relay tell_the_user and did_you_mean. reason not_registry_entity: explain entity_type. ambiguous true: ask which one. nif_caveat: say the link is not settled.

Read-only. Basic plan+. API key: X-API-Key (https://bormeapi.com/account).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "nif": "<nif>"
    },
    "name": "company_by_nif"
  }
}

Input Schema

NameRequiredDescriptionDefault
nifYesSpanish NIF/CIF, normally 9 characters, e.g. B12345674. Spaces, hyphens, dots and the ES VAT prefix (ESB12345674) are accepted; other country prefixes are not.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations' readOnly/idempotent profile, the description discloses domain-specific limits (BORME has no tax-ID field; 580k NIF mappings plus notice text cover only a minority), the meaning of nif_unmapped versus nif_revoked, and per-outcome relay instructions. It also names the auth and plan requirements (X-API-Key, Basic plan+), which annotations cannot express.

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?

Purpose, alternative, and next step are front-loaded, and nearly every fragment carries operational value (return fields, reason codes, relay actions) — justified given there is no output schema. It loses a point for telegraphic `reason x: ...` notation that reads as a compressed wall rather than structured guidance.

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?

With one parameter, no output schema, and a genuinely tricky data-coverage story, the description covers the return shape, null semantics for lei and website, coverage caveats, and the branch for each failure reason. An agent has everything needed to call it and interpret the result 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 coverage is 100% and the schema already spells out the 9-character format, accepted separators, and ES VAT prefix handling. The description adds only the NIF/CIF equivalence and error-path meaning rather than new detail about the parameter itself, so the baseline 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?

The opening states a specific verb and resource ("Look up a company by NIF/CIF") and immediately distinguishes the input shape from the sibling search_companies ("for names, search_companies"). An agent can tell exactly which tool handles tax-ID lookup without opening either schema.

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?

It gives an explicit selection rule (tax ID here, names there), a follow-up rule ("On a hit, call company_history with company_slug"), and branching handling for invalid_input, nif_check_character_failed, not_registry_entity, and ambiguous. That is when-to-use, when-not, and alternatives all in one place.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.