beel_list_recurring_invoices

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and idempotentHint=true, lowering the bar. The description adds value beyond that: the company-path scoping rule, the fact that a 403 is returned for unreachable or nonexistent NIFs (avoiding existence disclosure), and the pointer to fiscal guardrails. This is meaningful behavioral context consistent with the read-only profile — no contradiction.

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

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

The structure is sound: purpose first, endpoint second, warnings last. However, the fiscal guardrails block (AEAT invoice types, regime_key) reads as boilerplate that is more relevant to invoice creation than to read-only listing, adding length without directly helping an agent call this list tool. It is lean overall but contains content of questionable relevance.

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

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

For a read-only list tool with 7 params and no output schema, the description covers the critical pieces: scope source, security behavior, filters, pagination, and sorting. The main omission is the response shape (a list of recurring invoice template objects), though the schema already echoes pagination fields. Given annotations carry the safety profile, this is adequately complete.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 71%, so the schema already documents page/limit defaults, company_id scoping and security behavior, sort defaults, and the status enum. The description only generically says 'with filters and pagination' and adds no parameter-level detail. With the schema doing most of the work, a baseline 3 is appropriate; customer_id remains undocumented but that gap is in the schema, not the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 — 'Lists the recurring invoice templates of this company (NIF), with filters and pagination' — and adds an explicit scoping constraint ('Only the templates of the company in the path are returned'). It also names the endpoint. This distinguishes it clearly from sibling tools like beel_create_recurring_invoice, beel_get_recurring_invoice, and beel_patch_recurring_invoice.

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

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

It provides clear context on when to call: the company-scoped semantics and the explicit note that the header plays no part while company_id is the only source of context. It also warns to consult fiscal guardrails and points to beel_docs_search for exhaustive rules. However, it never names an alternative for a single template or non-recurring invoices, so exclusion guidance is left implicit.

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