Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_get_company

Read-onlyIdempotent

Fetches a company's identity, fiscal data, Test/Live activation, VeriFactu registration, and stored editable contact, legal, bank, and payment fields by company ID.

Instructions

Returns the identity and activation state of a company: its fiscal data, whether it is switched on in Test and in Live, and its VeriFactu registration state.

It also returns every field PATCH /v1/companies/{company_id} accepts — contact details, legal representative, bank details, IAE, activity start date, payment term and the rendering block — so what was written can be read back without keeping a copy of it. A field never set comes back absent: that means "nothing stored", not "hidden".

Its invoice series are not part of this response: read them from GET /v1/companies/{company_id}/series.

BeeL API endpoint: GET /v1/companies/{company_id} (reference: https://docs.beel.es)

⚠️ Read before calling:

  • Which company an operation acts on, and how that is selected. (resource: beel://guardrails/multi-nif)

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": {
      "company_id": "<company_id>"
    },
    "name": "beel_get_company"
  }
}

Input Schema

NameRequiredDescriptionDefault
company_idYesUnique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine response semantics beyond that: a field never set comes back absent, meaning 'nothing stored' rather than 'hidden', which prevents misreading an empty payload as a permissions problem. It does not cover rate limits or payload size, 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.

Conciseness4/5

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

Content is front-loaded: the return contents come first, then the exclusion, then the endpoint reference and the warning block. The enumeration of PATCH-accepted fields is slightly long but earns its place by establishing the read-back contract. The '⚠️ Read before calling' line is a single pointer rather than padded prose.

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

Completeness4/5

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

With no output schema, the description carries the burden of describing return content, and it does so at the right granularity: identity/activation, fiscal, VeriFactu, and the full writable field set, plus the absent-field convention. It also flags the non-obvious multi-NIF company-selection guardrail. Only minor gaps remain, such as nothing about the response envelope or nested rendering block structure.

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 single company_id parameter is documented in depth in the schema itself (UUID not NIF, account derivation, 403 for both unreachable and nonexistent companies). The description adds no parameter-level meaning at all, so the baseline 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 plus scope: identity and activation state, fiscal data, Test/Live enabled flags, and VeriFactu registration state. It also explicitly disclaims invoice series and names the sibling endpoint that serves them (GET /v1/companies/{company_id}/series), so it is distinguishable from beel_list_companies and beel_get_account.

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

Usage Guidelines4/5

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

It defines the boundary of the call clearly, saying what is included (every field PATCH /v1/companies/{company_id} accepts, so it doubles as read-back after a write) and what is excluded with a pointer to the series endpoint. It also routes to the beel://guardrails/multi-nif resource for company selection. It stops short of explicitly contrasting with beel_list_companies or beel_get_account, so no full when-to-use/when-not matrix.

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

Deploy Server

Other Tools