Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_get_recurring_invoice_stats

Read-onlyIdempotent

Retrieve company-wide recurring invoice stats: active schedule count, forecast monthly amount, and stopped invoicing from failed unattended generation. Returns whole-company figures; no filters.

Instructions

How many recurring schedules this company has alive, what they add up to per month, and how much invoicing is stopped because the unattended generation broke.

It is the whole company, and it takes no filters. It is an anchor, not a summary of whatever the list is showing: narrowing the list by customer or by status does not move these figures. Pagination does not apply either — the numbers cover every schedule of the company, not a page of them.

The two amounts are never added together. active.monthly_amount is a forecast of what is going to be invoiced; stopped.monthly_amount is invoicing that should be happening and is not. There is deliberately no grand total in the response.

The per-schedule figures behind them are the same ones GET /v1/companies/{company_id}/recurring-invoices publishes as amount, so the rows and this header cannot drift: adding the amount of every active row by hand gives active.monthly_amount exactly, to the cent.

Filters of the list are rejected, not ignored: sending status, customer_id or any other unknown parameter answers 400 naming it. Asking for a filtered header and getting whole-company figures back with a 200 would be worse than being told no.

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

⚠️ Read before calling:

  • Fiscal rules, domains simplified, taxes: beel_rules_list with domain, or resource beel://guardrails/.

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_recurring_invoice_stats"
  }
}

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.9.0

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real value with the 400-on-unknown-parameter behaviour, the fact that the two amounts are deliberately never summed, and the cent-exact agreement with the list endpoint's `amount`. It does not describe the response shape beyond field names or say anything about freshness/refresh timing of the underlying aggregation, so it sits a clear step above the annotation baseline but not at the top.

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-loaded with the answer's content in the first sentence, then scope, then the amount-separation caveat, then the 400 behaviour — good ordering with bolded anchors. It is somewhat longer than needed; the anchor-vs-summary point is restated across two sentences (filtering and pagination) where one would do.

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?

No output schema exists, and the description compensates by describing the returned amounts (`active.monthly_amount` as forecast, `stopped.monthly_amount` as missing invoicing), the absence of a grand total, and their exact correspondence to list rows. For a single-parameter read-only aggregate, nothing an agent needs in order to call or interpret it 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?

There is one parameter at 100% schema coverage, and its schema text already explains the UUID semantics, the derived account context, and the 403 behaviour for unreachable companies. The description adds only the negative constraint that no other parameter is accepted, which is guidance rather than parameter meaning — baseline 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 opening sentence names the exact quantities returned: count of live recurring schedules, their combined monthly amount, and the monthly amount of invoicing blocked by broken unattended generation. It also pins the scope ('the whole company') and contrasts with the list endpoint that publishes the per-row `amount`, so an agent can tell it apart from beel_list_recurring_invoices and beel_list_stats.

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 states strongly when this tool applies (company-wide aggregate, no filters, no pagination) and when it does not (any status/customer narrowing is rejected with a 400). It stops short of naming a sibling tool as the alternative for filtered queries — it references the REST endpoint rather than beel_list_recurring_invoices — so routing is inferable rather than explicit.

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