beel_get_recurring_invoice

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

The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the description's burden is reduced. The description adds useful behavioral context by scoping to a specific company NIF and by warning about fiscal guardrails that affect how returned data should be interpreted, which goes beyond the simple read-only annotation. It does not contradict annotations, and it mentions the endpoint and a pointer to exhaustive docs, though it does not detail side effects (none expected) or rate limits. This added context earns a 4.

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 description is front-loaded with the purpose and content, then adds endpoint and guardrail pointers in a structured warning block. It is relatively concise, but includes the endpoint URL (likely redundant with the tool name) and a lengthy warning list that could be externalized. However, it maintains a clear structure and doesn't waste words on the core purpose. It earns a 4 for being efficient and well-organized, though slightly over-inclusive.

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 simple read-only GET with two parameters, the description covers the return content (schedule, lines, next generation date) and points to guardrails and docs for exhaustive rules. Annotations handle the safety profile. It lacks explicit error semantics (e.g., 404 cases) but that is often omitted and the schema description for company_id partially covers 403 behavior. Given the resources and the tool's simplicity, the description is complete enough, though it could slightly clarify that this is a template, not an issued invoice, and that the ID refers to a template. A 4 is appropriate.

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 only 50%, meaning recurring_invoice_id has no schema description, and the tool description does not compensate for it. The description only reinforces that company_id is a NIF, which is already in the schema's detailed description. For recurring_invoice_id, no additional meaning is provided either in the tool description or the schema, leaving the agent to guess its purpose. Since the description adds no value for the undocumented parameter and merely echoes the schema for the other, it fails to compensate for the coverage gap, warranting a 2.

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 states a specific verb ('retrieves'), a specific resource ('full details of a recurring invoice template'), and the exact scope ('of this company (NIF)') and content ('schedule, template lines and next generation date'). It clearly distinguishes from sibling tools such as beel_get_recurring_invoice_history, beel_get_recurring_next_occurrence, and beel_list_recurring_invoices, which address different aspects. This is a precise, non-tautological purpose statement.

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?

The description gives clear context by specifying the endpoint and the scope (company NIF), but it does not explicitly state when to use this tool versus alternative getters or lists. It points to guardrails and beel_docs_search for deeper rules, but offers no exclusions or comparisons to siblings like beel_list_recurring_invoices or beel_get_recurring_invoice_history. This provides clear context without explicit 'when not to use' guidance, which aligns with a 4.

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