Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_list_stats

Read-onlyIdempotent

Retrieve per-company fiscal document counts and last invoice issue dates for an account, with pagination and search support.

Instructions

Returns, for each company of the account, how many fiscal documents it has issued and when it last issued one.

  • invoice_count: drafts, scheduled invoices and proformas are not counted; a rectifying invoice counts as a document of its own, and a voided invoice counts only when a live rectifying invoice compensates it.

  • last_invoice_at: issue date of the most recent document in that same set, or null when there is none.

  • Not a cursor: the count is not monotonic — voiding an uncompensated invoice lowers it and moves last_invoice_at backwards — so do not synchronise on it.

Paginated with the usual page/limit, and the usual defaults: without them you get the stats of the first 20 companies, not of all of them. One row per company, over the same universe and in the same order as GET /v1/accounts/{account_id}/companies — search included — so asking both with the same page, limit and search lines the two responses up company by company.

Endpoint: GET /v1/accounts/{account_id}/companies/stats

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNoPage number, starting at 1. The response echoes it back as `pagination.current_page`.
limitNoHow many items to return per page. The response echoes it back as `pagination.items_per_page`.
searchNoCase-insensitive filter on NIF, legal name or trade name — the same filter, over the same universe, as the one `GET /v1/accounts/{account_id}/companies` applies. Blank or omitted returns all.
account_idYesYour own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a `403` is returned when you do not reach it, the same response an account that does not exist gets.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.5.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / limit
      Added value: +{
+  "default": 20,
+  "description": "How many items to return per page. The response echoes it back as `pagination.items_per_page`.",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / page
      Added value: +{
+  "default": 1,
+  "description": "Page number, starting at 1. The response echoes it back as `pagination.current_page`.",
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / search
      Added value: +{
+  "description": "Case-insensitive filter on NIF, legal name or trade name — the same filter, over the same universe, as the one `GET /v1/accounts/{account_id}/companies` applies. Blank or omitted returns all.",
+  "type": "string"
+}
  2. First observedv0.3.1

TDQS

A4.7/5.0
Behavior5/5

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

Even with readOnlyHint and idempotentHint already present, the description adds substantial behavioral detail: what counts as an invoice, how voided and rectifying invoices affect the count, the non-monotonic nature, pagination defaults, and ordering alignment with the companies endpoint. This goes well beyond the annotations and helps the agent predict exact behavior.

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 dense but well-structured: a one-sentence summary, bullet points for field semantics, a warning about non-monotonicity, and a pagination/alignment note. Every sentence carries useful information, and key caveats are front-loaded after the summary.

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 no output schema, the description takes on the burden of explaining the result fields and their edge cases, and it does so thoroughly. It covers pagination defaults, ordering alignment, count semantics, and the endpoint path. Nothing an agent needs to invoke it correctly is missing.

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

Parameters4/5

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 enriches the parameters beyond the schema. It explains that omitting page/limit returns only the first 20 companies, and that search keeps the same universe and order as the companies list. These are meaningful semantics not present in the schema descriptions.

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 opens with a specific verb and resource: for each company, return fiscal document count and last issue date. It clearly distinguishes this stats endpoint from plain company listing, and the two returned fields are named and explained. The purpose is unambiguous even among a large sibling set.

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 explains when the data can be used, explicitly warns that the count is not a cursor and should not be synchronized on, and describes how results align with the companies list when using the same page/limit/search. It does not name an alternative tool to use instead, but the context and constraints are clear enough for an agent to decide.

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