BeeL MCP server

Official

by beel-es

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.3.1
Disambiguation4/5
Most tools have clearly distinct purposes, but a few create confusion: `beel_create_invoice_batch` actually applies operations to existing invoices rather than creating a batch, and generic names like `beel_get_by_id` are ambiguous without reading descriptions. Overall though, the vast majority target unique resource-action pairs.
Naming Consistency3/5
The general pattern is `beel_<verb>_<resource>`, but verbs are inconsistent (patch vs update, set vs create) and some names omit the resource (`beel_get_by_id`, `beel_patch_by_id`, `beel_activate_by_id`). This creates minor unpredictability but is still readable.
Tool Count1/5
With 122 tools, this is far beyond what a typical MCP server exposes. Even a comprehensive API would rarely need this many discrete operations; it likely overwhelms agents and increases the chance of misselection. This is an extreme mismatch for the typical tool count guideline of 3-15.
Completeness5/5
The tool set covers the full fiscal invoicing lifecycle: companies, customers, products, series, invoices (create, issue, void, correct, schedule, status), recurring invoices, payment connections, webhooks, accounts/members/invitations, documentation, and diagnostics. There are no obvious dead ends; every main workflow has the necessary read/write/delete operations.
Average 4.3/5 across 120 of 122 tools scored. Lowest: 3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 59 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=false (mutation) and destructiveHint=false. The description reinforces mutation by saying 'creates', but adds no extra behavioral context like side effects, idempotency behavior, or response format beyond what the schema's idempotency_key description already provides. No contradiction with annotations.
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?
Two concise sentences, front-loaded with the purpose and then a redundant endpoint line. No fluff, could drop the endpoint for slight improvement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema, the description doesn't mention success behavior or prerequisites. However, the complex tax rules are fully documented in the schema's nested $defs, so the description itself is minimally sufficient, though it leaves the agent to dig deep into the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, and the description does not add any parameter-level meaning beyond what the schema already provides. The mention of 'company (NIF)' echoes the existing company_id description. With moderate coverage, the description could have compensated but doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('creates') and resource ('product or service'), and scopes it to 'this company (NIF)'. It distinguishes from bulk creation only by name, not explicitly, so it's clear but not fully differentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this versus `beel_create_products_bulk` or when not to use it. No prerequisites (e.g., company existence) are mentioned. Usage context is implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the idempotentHint=true annotation. It states that a company with no active representation is rejected with 400, implying that a second call after a successful cancellation fails, which conflicts with idempotency. This is an annotation contradiction. The description does add useful details (e.g., consequences and state-transition nature) but the contradiction undermines transparency, so it scores 1.
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?
The description is two short paragraphs and an endpoint line. The main action is front-loaded, and the consequences are explained in a few sentences. It avoids excessive detail while covering the essential points. It is appropriately concise without being vague.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description covers the core action and effects. It mentions what happens on cancellation (cannot submit invoices) and what remains untouched (activation and non-VeriFactu invoices). However, it fails to clarify idempotency, which is relevant given the annotation, and does not indicate what a successful response looks like. While not extensive, the gaps are not critical for a simple state transition, so a 3 is appropriate.
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?
The input schema contains a 100% description coverage for company_id, including context about the BeeL-Active-Company header and error scenarios. The tool description does not add any parameter-level guidance beyond what the schema provides. Baseline of 3 is appropriate when the schema fully documents the parameter.
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 clearly states the action: 'Cancels the active AEAT representation of a company (NIF).' It identifies the specific resource (AEAT representation) and the target (company NIF), and distinguishes itself from siblings like beel_generate_representation and beel_get_representation by focusing on cancellation. The first sentence alone is sufficient to understand the tool's unique purpose.
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 provides clear context on when to use the tool: the cancellation prevents invoice submission to AEAT until a new document is generated and signed. It also implicitly excludes use when there is no active representation (rejected with 400). However, it does not explicitly name alternatives or state 'use this instead of X', but the context implies that a new representation can be generated afterward. This is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutating nature is known. The description adds only the endpoint string, which is not behavioral. It does not disclose idempotency (already hinted) or any side effects, permissions, or error behavior that annotations don't cover. Given the annotations, the bar is lower, but the description still contributes little beyond repeating 'deletes'.
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?
Two short sentences with zero filler. The action 'Deletes a product' is front-loaded, followed by the endpoint for reference. Everything present is useful and there is no redundancy with annotations or schema.
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?
For a simple delete tool with two parameters and no output schema, the description gives enough to invoke it correctly: what it deletes and on which company. It does not mention error handling or response format, but annotations cover idempotency and safety, keeping the description adequate without being exhaustive.
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?
Both parameters (company_id and product_id) are fully described in the schema with 100% coverage, including specific details about company_id semantics and product_id format. The description itself adds no parameter information, so it does not exceed the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'deletes' and the resource 'a product from the catalog of this company (NIF)', which is specific and distinct from bulk deletion. It does not explicitly name sibling tools like beel_delete_products_bulk, but the singular 'a product' implies a single-item operation, making it distinguishable at the surface level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided. The description implies it is for deleting one product from a company, but it does not contrast with bulk delete or other delete tools. An agent would need to infer the appropriate use case from the singular noun and endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds the endpoint and fiscal guardrails link but doesn't specify return format or error behaviors beyond what the schema covers. The guardrails mention when an invoice can be changed, but that's more about the invoice lifecycle, not this tool's 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?
Concise and front-loaded. Two sentences plus a callout and pointer. No fluff. The endpoint and guardrails earn their place.
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?
For a read-only retrieval tool with annotations covering safety, the description is mostly complete. It points to docs for exhaustive rules. However, the phrase 'full details' is vague; with no output schema, a note on what fields are returned would improve completeness.
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 coverage is 100%, with company_id having an extensive description. The tool description adds no parameter details beyond the schema. Baseline 3 applies since schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a clear action ('Retrieves the full details of an invoice') and specifies the resource scope ('of this company (NIF)'). It is distinct from list and PDF tools though it doesn't name alternatives, so it lacks explicit sibling differentiation but is still specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like beel_list_invoices or beel_get_invoice_pdf. The fiscal guardrails note is about invoice modification rules, not tool selection. It points to docs but doesn't clarify usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which match a search operation — no contradiction. The description adds the ranked-relevance behavior ('Returns the most relevant sections') but provides no further detail on result ordering, ranking cutoff, or how many sections beyond the limit parameter. With annotations covering the safety profile, the added value is modest.
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?
Two information-dense sentences, front-loaded with the search domain and return behavior before the usage guidance. No filler or redundancy; every clause carries content.
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?
For a low-complexity, read-only search tool with fully documented parameters and an open-world annotation, the description is adequate. It could mention result count or ordering semantics, but nothing an agent needs to invoke the tool correctly 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?
Schema description coverage is 100%, so both terms and limit are already documented in the schema. The description's topic enumeration (VeriFactu, corrective invoices, etc.) implicitly guides what search keywords are useful, but it adds no syntax, format, or semantic detail beyond the schema. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (search), a specific resource (BeeL API documentation), and enumerates content domains (VeriFactu, invoice types, taxes, regime keys, corrective invoices, international customers, worked examples). It is distinguishable from sibling doc tools beel_docs_list and beel_docs_get via the 'search' verb and the ranked-sections return, but it never explicitly names those alternatives to stake out its niche.
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?
Provides an explicit situational trigger: 'Use this before building non-trivial invoices or when unsure about a fiscal rule.' This is concrete and actionable. It does not state when NOT to use it or explicitly route to the sibling doc tools (beel_docs_list, beel_docs_get), but the positive trigger is 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the endpoint, which is technical but not behavioral, and mentions 'complete details' about output, not behavior. It does not disclose error cases like 404 on missing customer, which would be useful but not critical given the read-only nature. Annotations carry most of the burden, and the description adds minimal value beyond that, so a 3 is appropriate.
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 a single sentence that states the purpose, followed by the endpoint. It is concise, front-loaded, and contains no filler. Every word earns its place, and the endpoint provides a useful technical reference without bloat.
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?
For a simple read operation with annotations covering safety and schema covering parameters, the description is largely complete. It tells the agent what the tool does and the context (per-company). The only gap is the lack of output structure, but since there is no output schema, the description could have mentioned that it returns the full customer object. However, for a get operation, the agent can reasonably infer the return shape from the resource. Overall, the information is sufficient for correct invocation.
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%, with both company_id and customer_id having detailed descriptions in the schema. The description itself adds no parameter-specific meaning beyond the endpoint path, which is redundant. Since the schema already documents the parameters thoroughly, the description does not need to compensate, and the baseline score of 3 stands.
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 clearly states the verb 'Retrieves' and the resource 'complete details of a customer', which is specific and unambiguous. It includes the exact endpoint, distinguishing it from list operations like beel_list_customers. The sibling differentiation is implicit via the endpoint path and the singular resource, making the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for fetching a single customer by ID, nor does it suggest using beel_list_customers for listing. The agent must infer usage from the name and parameter structure, which is not explicit. No exclusions or conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds the endpoint and clarifies that the company is identified by NIF, but it does not describe response structure, error behavior, or any side effects beyond what annotations imply. It adds minimal behavioral context beyond the structured metadata.
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 extremely compact, consisting of two sentences with no filler. It front-loads the purpose and adds a technical endpoint reference that is useful for implementation. Every word earns its place, and it is well-structured for quick parsing.
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?
For a simple read-only operation with 2 parameters, the description is largely sufficient. Annotations cover safety, and the schema covers parameters. The main gap is that no output schema exists and the description doesn't hint at what 'details' includes (e.g., fields, nested objects), but given the tool's simplicity and the presence of readOnlyHint, this is a minor omission. The description could be more explicit about response format but is not critically incomplete.
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?
The input schema provides 100% coverage with descriptions for both parameters. The description only echoes the endpoint and mentions 'NIF' but does not add new semantic meaning beyond the schema's own parameter descriptions. Since the schema already explains the parameters adequately, the description adds little value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Retrieves the details of a product') and identifies the resource (a product of a specific company). It is unambiguous and distinguishes itself from listing tools by focusing on a single product. However, it does not explicitly differentiate from the broader `beel_get_by_id` sibling, so it misses full sibling discrimination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like `beel_list_products` or `beel_get_by_id`. Usage is implied by the tool name and description, but there is no explicit guidance on conditions or exclusions. It leaves the agent to infer that it is for fetching a specific product's details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already signals a write operation, and the description adds useful behavioral details: the default attachment of the PDF and the fallback to customer-configured recipients when no recipient is given. However, it does not disclose side effects beyond sending (e.g., email quota consumption, non-idempotency despite idempotentHint=false, or potential errors like exceeding size limits). The description enriches behavior but leaves gaps that the schema partially fills.
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 two sentences plus an endpoint line, with no superfluous content. The primary action and default behavior are front-loaded, making it easy for an agent to quickly grasp the function. It is concise without sacrificing essential information.
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?
The description covers the core behavior (sending invoice via email, default PDF attachment, recipient fallback) and provides the endpoint. While it omits details about the request body options and idempotency, the schema is rich enough for an agent to infer them. For a send-action tool with a well-documented schema, the description is adequate, though it could benefit from a note that the body contains optional fields like cc, subject, and language.
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?
With 75% schema description coverage, the parameters are already well-documented in the schema. The description repeats the attach_pdf default and recipient fallback, which are already stated in the schema fields (attach_pdf has default:true, recipients says 'If not specified, uses the customer's email'). It does not add new meaning beyond summarizing existing schema content, so it only meets the baseline expectation.
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 states a clear action ('Sends the invoice by email'), identifies the resource (invoice), and specifies the default behavior (attaching its PDF). It distinguishes the tool from others by focusing on the email-sending action with the endpoint provided, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention sibling tools such as beel_create_invoice_delivery or beel_get_invoice_pdf, nor does it state conditions under which this tool should be avoided. It only implies the use case (sending an invoice by email) without exclusions or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses idempotency behavior (retry on deprecated flat route replays) and fiscal guardrails (name mismatch affects invoice submittability), which are not present in annotations. This adds value beyond the basic read/write flags, even though details like error responses are omitted.
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?
The description is concise, with the core purpose in the first sentence, followed by a warning and a pointer to docs. No redundant information; the structure is efficient and front-loaded.
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?
The tool has a complex request schema with many nested objects. The description provides high-level context and warns about fiscal issues, but does not list required fields or defaults. It references beel_docs_search for exhaustive rules, acknowledging incompleteness. Given the schema's richness, this is adequate, though not fully comprehensive.
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?
The description does not explain any parameters directly; it only mentions Idempotency-Key in a behavioral context. The schema provides descriptions for many fields (67% coverage), but the description does not compensate for the missing 33% or add nuance to the existing ones, so it stays at the baseline for high coverage.
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 states 'Creates a new customer under this company (NIF)' which is a specific verb-resource pair and clarifies the scope (company). It also includes the endpoint. This distinguishes it from bulk creation (beel_create_customers_bulk) and other customer operations, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not mention when to use this tool versus alternatives. It does not say to use for single customer creation or to use bulk for multiple, nor does it contrast with patch or delete operations. The only guidance is a pointer to docs for exhaustive rules, but no explicit selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail beyond annotations: it explains that last_status can be REJECTED or QUEUED, that count > 0 does not imply delivery, and that ids with no emails are omitted. These caveats help the agent interpret results correctly.
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?
The description is well-structured with three short paragraphs. The first sentence states the primary purpose and return values, followed by clarifying caveats and an endpoint reference. It is somewhat verbose but each sentence adds value; no filler.
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 explains the response semantics: fields like last_status and count, plus behavior for missing ids. It does not specify every field name or timestamp format, but it provides enough to call the tool and understand results. Annotations cover safety, so missing details like pagination are acceptable.
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 coverage is 100%; both parameters have descriptions. The tool description does not add parameter-level details beyond the schema, such as constraints or formatting. It references related_entity_ids generally, but the schema already covers it, so the description adds no marginal value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (returns email delivery indicators for related entity ids) and what is returned (count, last status, timestamp). It distinguishes from loading full email history, but does not explicitly name sibling tools like beel_get_email_delivery or beel_list_email_deliveries, so differentiation is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool ('show the state of an entity's email without loading its full history'), which is a clear context. However, it does not state when NOT to use it or explicitly point to alternatives for full history or individual delivery lookups. The guidance is present but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the specific endpoint and the note that output matches the list shape, which provides useful contextual detail. However, it doesn't discuss error handling, pagination, or other behavioral traits, though the annotations lower the burden.
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 minimal and efficient: a single-sentence purpose followed by the endpoint. It's front-loaded with the main action and includes the endpoint for clarity, with no unnecessary filler. Every word earns its place.
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?
For a simple GET-by-ID operation with two well-documented parameters, the description is complete. It states what is returned, references the output shape from the list endpoint to set expectations, and benefits from annotations covering safety. No additional information is needed for an agent to call this tool correctly.
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?
The input schema has 100% coverage, with both 'account_id' and 'member_id' fully described. The description doesn't add any parameter-specific meaning beyond what the schema already provides; it only states that the tool returns one member. Since the schema does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns one member of an account, with a specific verb (returns) and resource (member). It also notes the output shape matches the list endpoint, adding context. However, it doesn't explicitly name a sibling like 'beel_list_members' to differentiate, though the purpose is unambiguous on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving a single member by mentioning 'one member' and referencing the list shape, but it doesn't explicitly state when to use this tool versus alternatives like 'beel_list_members' or 'beel_patch_member'. No 'when not to use' guidance is provided, leaving the routing to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false), so the bar is lower. The description adds genuine context beyond annotations by stating the endpoint, the pagination behavior, and the fact that only the path company's customers are returned. It does not contradict annotations — 'Returns a paginated list' aligns with the read-only hints — but it doesn't elaborate on error or edge cases, so a 3 is fair.
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?
Three short sentences with no fluff, front-loaded with the core purpose. The scope restriction is placed early. The endpoint line is marginally redundant since the path is implied by the company_id parameter, but it's still efficient documentation reference. Nearly zero waste.
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?
For a read-only filtered list tool with 100% schema coverage and a rich parameter set, the description covers the essentials: pagination, filtering, and scope restriction. The default active=true behavior is already in the schema, so not repeating it is fine. With no output schema present, a brief note on return shape could help, but the definition is adequate for an agent to call it correctly.
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%, so the schema already documents all 13 parameters in detail (e.g., active defaulting to true, deleted customers never returned, NIF reachability behavior). The description only adds 'with optional filters', which adds little over the schema. Baseline 3 is appropriate since the description doesn't need to compensate for a coverage gap.
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 states a specific verb-object pair ('Returns a paginated list of the customers of this company (NIF)') with optional filters, making the resource and scope unambiguous. It clearly differentiates from siblings like beel_list_invoices and beel_list_products by naming customers specifically, and the title 'List Company Customers' reinforces it. An agent can tell what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the scope restriction ('Only the customers of the company in the path are returned') and mentions optional filters, giving useful context for when pagination/filtering is needed. However, it never explicitly names alternatives (e.g., beel_get_customer for a single customer, beel_create_customer for adding) or states when-not conditions. The guidance is implicit context, not active routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnly=false, so the description need not restate that. It adds a valuable behavioral constraint not in the annotations: the last OWNER cannot be removed. This is a meaningful addition that helps an agent anticipate a specific error condition. However, it does not mention other consequences (e.g., whether grants are cascaded or if the operation is reversible).
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 two sentences plus an endpoint line, with no redundant phrasing. It front-loads the primary purpose, then adds the key constraint, and the endpoint is a terse, useful reference. Every line earns its place.
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?
For a simple two-parameter delete operation with annotations already covering the destructive nature, the description is largely sufficient. It covers the action, the key restriction, and the endpoint. It could be more complete by noting that once a member is removed, their access is permanently revoked and related grants/associations may be affected, but the lack of an output schema makes this acceptable overall.
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?
The schema covers 100% of parameters with detailed descriptions (e.g., account_id decides the target account, returns 403 on mismatch). The tool description adds no additional parameter-level information beyond what the schema already provides. Per the baseline rule for high schema coverage, a score of 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 description states a precise action ('Removes a member's access to the account') with a clear resource and verb, and the endpoint line reinforces the resource. It is unambiguous and easily distinguishes itself from other member-related tools like beel_delete_member_grant (which removes a grant, not the membership itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. It does not mention that beel_delete_member_grant only removes specific permissions while this removes the entire membership, nor does it describe any prerequisites or conditions other than the last-OWNER restriction. The user must infer the appropriate context from the tool name and minimal description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds concrete behavioral details: it explains coherence rules (regime key 18 only for IVA), specific error responses (422 INVALID_REGIME_KEY_FOR_TAX_TYPE, 422 RECARGO_REQUIRES_REGIME_RE), and that the operation replaces the whole configuration. This goes beyond the annotations and provides operationally useful context without contradicting them.
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 a single compact paragraph of about 90 words. It front-loads the core purpose, then quickly covers the most critical coherence constraint and error cases. There is no redundancy or filler; every sentence contributes operational value. This is exemplary for con</anner>
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?
The description covers the primary behavior, critical domain rules, and error responses for this write operation. It does not describe the success response or the exact structure of the updated configuration, but such details are not essential given the absence of an output schema and the fact that the schema already documents field behavior. The description is complete enough for an agent to invoke the tool correctly and anticipate common failures.
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?
The input schema already contains extensive descriptions for every field, including the nested TaxInfo, RegimeKey, PaymentMethod, and others, with detailed semantics and examples. The description primarily reiterates the high-level fields (default regime, percentage, IRPF, surcharge) without adding new meaning beyond the schema's own rich documentation. It thereby does not significantly enhance parameter understanding, though it does not hinder it either.
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 specifies a clear action ('Replaces the tax configuration of a company') and identifies the exact resource (NIF), the fields it covers (default tax regime, main percentage, regime key, IRPF, equivalence surcharge), and the endpoint (PUT /v1/companies/{company_id}/tax-configuration). This distinguishes it from the get_tax_configuration sibling and other update tools like beel_update_verifactu_configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention conditions where another tool should be preferred. It implies its use by 'Replaces the tax configuration' but offers no guidance on alternatives (e.g., get_tax_configuration for reading, update_verifactu_configuration for VeriFactu-specific settings). It lacks 'when-not-to-use' or exclusion statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says 'This operation only reads the register: it creates nothing and stores no customer,' which contradicts the annotation readOnlyHint=false (indicating the tool may modify state). This is a direct contradiction that undermines trust. Although the description provides rich behavioral detail (status meanings, legal entity semantics, error handling), the contradiction is a severe flaw. Per rules, score 1.
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?
The description is fairly long (~300 words) but well-structured: purpose first, then nuanced behavior, then error handling, endpoint, and guardrails. Most sentences add essential context. It could be tightened (some redundancy) but is organized and front-loaded with the core purpose. The pointers to docs and guardrails justify the length.
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?
Given the tool's complexity and the absence of an output schema, the description thoroughly covers response semantics (status, valid, legal_name_verified, census_status), error cases (INVALID, FIELD_BLANK), and behavioral nuances for individual vs legal entity. It also includes a guardrail reference and a pointer to exhaustive docs. Nothing critical is missing for an agent to call it correctly.
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?
The schema coverage for the top-level body parameter is 0%, but the nested properties have detailed descriptions. The tool description adds value by explaining the meaning of valid:true for individuals vs legal entities, which guides whether to send legal_name. It also clarifies error semantics (422 vs 200). This goes beyond schema and aids correct parameter usage, though it does not introduce entirely new parameter documentation.
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 states a specific action ('Checks a NIF or CIF against the AEAT register through VeriFactu') and specifies the resource and outcome. It clearly differentiates from the many sibling tools by its unique validation purpose and also provides the endpoint. The purpose is explicit and unambiguous.
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?
The description clearly indicates when to use the tool (to validate a Spanish tax ID) and provides important usage nuances (bad syntax returns 200 INVALID, empty NIF returns 422). It points to beel_docs_search for exhaustive rules and mentions fiscal guardrails. It does not explicitly compare with alternatives, but the tool's unique purpose makes exclusion less necessary. A minor gap is not stating 'when NOT to use', but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds important behavioral context: it permanently deletes the template and cancels pending scheduled generations, while clarifying that already-generated invoices remain unaffected. This goes beyond the annotations by describing specific side effects and scope. No contradiction with annotations.
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?
The description is front-loaded with the core purpose, followed by the endpoint and then important guardrails. The guardrails section is somewhat lengthy but serves as a necessary warning for fiscal compliance. The structure is clear and logically ordered, though the guardrail references could be more concise.
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?
For a destructive tool with no output schema, the description covers the essential side effects (permanent deletion, cancellation of pending generations, non-impact on generated invoices) and provides a warning about fiscal rules. It lacks explicit guidance on how to obtain recurring_invoice_id or what the response will be, but those are minor gaps for this operation.
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 coverage is 50%: company_id has a detailed description, but recurring_invoice_id has none. The description adds some meaning for company_id (e.g., 'of this company (NIF)') but does nothing for recurring_invoice_id. It does not compensate for the missing parameter description, though it partially leverages the existing schema description for the first parameter.
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 states a specific action: 'Permanently deletes a recurring invoice template of this company (NIF) and cancels any pending scheduled generations.' It also clarifies the scope ('Invoices already generated from it are not affected'), which distinguishes it from related delete tools like beel_delete_invoice. The purpose is unambiguous and clearly identifies the resource and the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to permanently remove a recurring invoice template) but does not explicitly mention alternatives or exclusions. For example, it does not contrast with beel_set_recurring_invoice_status (which might deactivate rather than delete) or beel_skip_recurring_invoice. The warning about fiscal guardrails suggests prerequisites, but no explicit 'when not to use' is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower — and the description builds on that rather than repeating it. It adds genuine behavioral value: the automatic-flow skip semantics with the specific failure code, the note that 'the environment is resolved from the request context and takes no input,' and a pointer to fiscal guardrails about numbering being non-rewritable. The only slight mismatch is that the 'numbering can never be rewritten' warning is tangential for a read-only tool, but it is still domain-relevant. No contradiction with annotations.
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?
The purpose is front-loaded in the first sentence, followed by a compact, scannable structure: behavior note, endpoint line, guardrails warning, and docs routing. Every sentence earns its place and the guardrails warning is information-dense. It is mildly verbose for a one-parameter read-only tool — the endpoint duplication and the warning block could be tighter — but the organization makes it efficient to parse.
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?
For a single-parameter, read-only, annotation-rich tool with no output schema and no nested objects, this definition is highly complete: it states what is reported per document type, the domain consequence of missing defaults, the exact endpoint, and where to find exhaustive rules. The only minor gap is not hinting at the return shape or whether results paginate — but the description's 'reports... which one' already sketches the per-document-type structure, so nothing an agent needs to call it correctly 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?
Schema description coverage is 100%, and the company_id schema description is exceptionally rich — it states the NIF is the only source of context, that BeeL-Active-Company plays no part, and details the 403 behavior and non-disclosure guarantee. The tool description adds minimal parameter meaning beyond restating 'NIF'; its only contribution is confirming that 'no input' other than the schema parameter is needed, which the schema's 'only source of context' phrasing already implies. A solid baseline-3 case where the schema carries the full burden.
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 uses a specific verb ('Reports') against a precise resource ('for each DocumentType... whether the company (NIF) has a default invoice series and which one'). It scopes itself to automatic invoicing flows, which separates it from siblings like beel_get_series and beel_list_series. The behavioral consequence (no-default types cannot be issued without an explicit series_id and are skipped with failure.payment.skip.missing_default_series) sharpens the purpose even further.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the operational context well — it explains when the result matters (automatic flows skip types with no default) and routes to beel_docs_search for exhaustive rules. However, it never explicitly contrasts itself with the natural mutating counterparts beel_set_default_series and beel_ensure_default_series, nor states when one should be preferred over this read-only check. Usage guidance is implied through context rather than stated as exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable context about fiscal guardrails (AEAT invoice type and regime_key), which are important constraints for the API call. It also mentions the endpoint, aligning with the purpose. There is no contradiction with annotations.
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?
The core purpose is conveyed in two concise sentences, followed by a bullet list of guardrails. It is front-loaded with the main function and the guardrail list is relevant and not excessive. The structure is clean and efficient.
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?
This is a simple read operation with two required parameters, and the description covers what it returns (invoices with status and generation dates). Annotations cover the safety profile, and the guardrail pointer adds necessary context. The only omission is explicit pagination/ordering, which is not critical for this history retrieval. The level of detail is sufficient for correct invocation.
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 50%: company_id has a detailed description explaining its role and error behavior, but recurring_invoice_id has none. The tool description does not add any parameter semantics beyond the schema. The missing parameter is inferable from the tool name, but the description does not compensate for the gap.
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 clearly states a specific verb ('Returns') and resource ('invoices previously generated from this recurring template'), including the details of status and generation dates. This distinguishes it from siblings like beel_get_recurring_invoice (which retrieves the template itself) and beel_list_recurring_invoices (which lists templates). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. It only describes its function and points to fiscal guardrails. The usage context is implied by the name and description but not made explicit, so an agent must infer when this is the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about fiscal guardrails (how invoice numbers are formed and why they cannot be rewritten) and points to a resource for details. This is beyond annotations and provides useful behavioral context, but it does not describe return format, error handling, or other side effects. It adds some value but not a rich behavioral layer, consistent with a baseline of 3 given strong annotations.
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 concise and well-structured: it front-loads the core purpose, then provides the endpoint, then a critical warning with a resource link, and finally points to exhaustive documentation. Every sentence earns its place; there is no filler. It is neither too short nor overly verbose.
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?
For a simple get-by-ID tool, the description is complete: it states what is returned, provides the endpoint, alerts to critical guardrails, and tells the agent where to find exhaustive rules (beel_docs_search). It does not have an output schema, but it lists the returned fields. No additional context (e.g., pagination, ordering) is needed for a single-resource fetch. The pointer to docs ensures any deeper questions are addressed.
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 coverage is 100%: both company_id and series_id have descriptions. The company_id description in the schema is notably detailed (explaining it is the only source of context and that unreachable NIFs return 403). The tool description itself does not add meaning beyond that, except implicitly tying company to NIF. Since the schema already documents parameters well, 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 description clearly states that the tool returns one invoice series of a company, listing the specific fields returned (code, format, counter state, document type, default flag). It uses a specific verb ('Returns') and resource ('invoice series'), and the scope is unambiguous. It distinguishes from siblings like beel_list_series (which presumably lists many) and beel_get_default_series (which gets the default) by focusing on a single series by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: it returns a single series, so an agent would infer to use it when fetching a specific series by ID. However, it does not explicitly state when to use it versus alternatives like beel_list_series or beel_get_default_series, nor does it mention any prerequisites or exclusions. This is implied usage rather than explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context by noting that the configuration belongs to the NIF and that the NIF in the path is authoritative, which is not inferable from annotations. The guardrails reference and docs pointer provide additional operational context.
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?
The description is compact and front-loaded with the primary purpose. The endpoint, guardrails warning, and docs reference are each purposeful and non-redundant. Slightly longer than necessary due to the guardrails section, but each part serves a function, so it earns a 4 rather than a 5.
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?
For a simple getter with one parameter and no output schema, the description covers the essential aspects: what it retrieves, the NIF selection mechanism, and references to guardrails and docs. Missing is a hint at what the returned configuration contains, but given the tool's simplicity and the annotations, the description is nearly complete.
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 schema's parameter description for company_id is exceptionally detailed (explains NIF derivation, header irrelevance, and 403 behavior). The tool description adds no additional parameter information, so a baseline of 3 is appropriate since the schema carries the burden.
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 states the verb 'Retrieves' and the resource 'VeriFactu configuration of this company (NIF)' clearly. It further clarifies that the NIF in the path determines which configuration is returned, and provides the exact endpoint. This distinguishes it from sibling tools like beel_get_tax_configuration and beel_update_verifactu_configuration by the explicit resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when needing the VeriFactu configuration) and points to beel_docs_search for exhaustive rules, but it does not explicitly state when not to use it or contrast it with alternative tools like beel_get_tax_configuration. The fiscal guardrails note gives contextual guidance but not selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds crucial behavioral context: only present fields are updated, null clears fields, and the recipient survives lines changes. It also warns about fiscal guardrails, which is beyond annotation coverage.
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?
The description is well-structured with the core behavior stated first, followed by a warning block and a pointer to documentation. It avoids redundancy and keeps the key information accessible without excessive length.
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?
For a complex PATCH operation, the description includes the endpoint, fiscal guardrails, and references to docs for exhaustive rules. It does not cover return values (no output schema) or idempotency (handled by annotations), but the provided context is sufficient for an agent to call the tool correctly with the schema's guidance.
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 low (33%) at the top level, but the body's nested schema has extensive descriptions. The description adds the essential 'null clears' rule that governs how parameters in the body are interpreted, but it does not elaborate on individual fields. It compensates partially for the schema gap.
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 clearly states the tool 'Updates only the fields present in the body', naming the resource as 'recurring invoice' and giving the endpoint. It explicitly distinguishes behavior from a full update by noting the recipient survives changes to lines, making the purpose unambiguous even among sibling tools like beel_patch_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for partial updates of recurring invoices and includes important prerequisites (read fiscal guardrails, call beel_docs_search for exhaustive rules). However, it does not explicitly contrast with alternative tools or specify when NOT to use it, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool changes state (marks and unmarks), which is consistent with readOnlyHint=false. It adds detail beyond annotations: unmarking the previous default, rejecting inactive series with 400, and repeating the call being a no-op (matching idempotentHint=true). It does not contradict any annotation and provides useful behavioral context.
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?
The description is compact: two sentences of action/constraints, an endpoint line, and pointers to guardrails and docs. It is front-loaded with the purpose and constraints, and every sentence contributes value. The endpoint line is slightly redundant given the tool name but adds precision. No fluff.
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?
For a mutation tool with side effects, the description covers the effect (mark/unmark), the active-series constraint, idempotency, and points to external resources for exhaustive rules. It lacks an explicit return value, but there is no output schema, and the description focuses on the operation's effects. It is sufficiently complete for an agent to call correctly, especially with the guardrail pointer.
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 both parameters are well-described, so the baseline is 3. The description reinforces the semantic role of company_id and series_id (e.g., 'for this company (NIF)') but does not add new syntax or format details beyond what the schema already provides. It does not need to compensate for a coverage gap.
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 clearly states the action: 'Marks an invoice series as the default of its document type for this company (NIF), and unmarks the previous one.' It uses a specific verb, resource, and scope, and mentions idempotency. It distinguishes itself from other series tools by explaining exactly what 'set default' entails, which is not merely a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides preconditions (series must be active, only one default per company/document type) and points to guardrails and docs for exhaustive rules. However, it does not explicitly compare against the sibling 'beel_ensure_default_series' or state when to prefer this over alternatives. It gives context but no clear exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal mutability (readOnlyHint=false), and the description adds valuable behavioral context: it states that partially failing PDF attachments are reported in `failures` and the email is still sent for the rest. It also clarifies that no recipient is inferred from profiles. This goes beyond the annotation hints and aids the agent in anticipating partial failures. No contradiction with annotations.
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 two sentences (plus an endpoint line) with no redundancy. The primary action is front-loaded, and the constraint and failure handling are conveyed in a compact, structured way. Every sentence earns its place without padding.
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?
For a tool that sends email deliveries, the description covers the key behavioral aspects: the purpose, the limit, the requirement for recipients, and the failure reporting. It also includes the endpoint for debugging. However, it does not describe the response structure beyond `failures`, which is somewhat important given there is no output schema. This leaves minor ambiguity about what else the response contains, but the core use case is clear.
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 coverage is 67% (most parameters have descriptions). The description adds a bit of meaning by implying invoice_ids are invoices whose PDFs are attached and by restating the recipient requirement, but these align with schema constraints (maxItems=200, minItems=1). The idempotency_key behavior is described in the schema, not the tool description. The description compensates only slightly for the coverage gap, so a 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 description states a specific action ('Sends one email carrying the PDFs of up to 200 invoices of this company as attachments'), a clear resource (invoices of the company), and scope (up to 200). It distinguishes itself from siblings like beel_send_invoice (single invoice) and beel_get_email_delivery (retrieval) by describing the multi-invoice email delivery behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to send multiple invoices by email) and provides a strict requirement (at least one recipient, no profile inference). However, it does not explicitly contrast with alternatives or state when not to use it (e.g., for a single invoice use beel_send_invoice). The context is clear but lacking explicit exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive and non-read-only behavior, but the description adds valuable specifics: the 404 response when the invitation is already accepted, revoked, or expired, without disclosing which; and that revocation does not remove the invitation from the list. It also provides the HTTP endpoint. These details go beyond the annotations and help the agent anticipate outcomes.
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?
The description is compact, with the key behavior front-loaded in the first sentence and supporting details in the second. The endpoint line is a minor redundancy but adds clarity. There is no fluff; every sentence contributes to understanding the operation.
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?
For a simple delete operation with two parameters, the description covers the core behavior, error conditions, and side effects (non-removal). It does not explain what the invitation_id is, but that is partially inferred. It also does not discuss potential side effects beyond revocation, but given the annotations and schema, it is reasonably complete for an MCP tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema provides a detailed description for account_id, the invitation_id parameter has no description and the tool description does not compensate for it. Schema description coverage is 50%, so the description should clarify the invitation_id parameter, but it only mentions it in the endpoint line without adding semantic meaning. This is a notable gap for an agent trying to construct a valid call.
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 clearly states the action ('Revokes a PENDING invitation') and the effect ('its acceptance link stops working'). It distinguishes itself from list/get/create invitation tools by specifying the state constraint and the non-removal behavior. The verb and resource are precise, leaving no ambiguity about what the tool does.
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?
While it does not explicitly name sibling tools, it provides strong contextual guidance: only pending invitations can be revoked, and revocation does not remove the invitation from the list. This implicitly tells an agent when this tool is appropriate (revoking an invitation) and when it is not (if removal is desired). It lacks an explicit 'use X instead' statement, which would merit a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive and idempotent behavior, but the description adds valuable context: the operation is partial, reporting successes and failures, and returns 200 with a body instead of 204. This explains the behavioral nuance beyond what annotations convey, and there is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by the limit and partial-success nuance, and ends with the endpoint. Two sentences plus a URL convey the essential information without verbosity, making it highly concise and well-structured.
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?
For a simple 2-parameter tool with no output schema, the description covers the essential context: what it does, the batch limit, partial failure behavior, and the response code rationale. It lacks only explicit details about required authentication or permissions, but those are likely handled elsewhere and not critical for a delete operation.
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?
Both parameters are already described in the schema with 100% coverage, so the baseline is met. The description mentions 'this company (NIF)' but does not add new parameter semantics beyond what the schema already provides; it mainly reinforces the clarification already present in the `company_id` description.
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 clearly states the action ('Deletes the products listed in `ids` from the catalog of this company (NIF)'), specifies the resource type and scope, and explains the 100-ID limit. It distinguishes itself from the singular 'beel_delete_product' by emphasizing bulk deletion and partial success, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical usage guidance (send multiple requests if more than 100 IDs) and explains the 200-with-body vs 204 distinction, but it does not explicitly name alternatives such as 'beel_delete_product' for single deletions. The when-to-use is implied rather than directly stated, so it lacks explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: the 5-minute URL expiration, the logic of serving the generated vs signed document, and a specific error condition (400 for not yet generated). This goes beyond what annotations provide, though it doesn't mention the 403 behavior (which is in the parameter schema).
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 compact and front-loaded with the core purpose. The first sentence states what it returns and its validity, the second addresses the document state logic, and the third covers the rejection case. The endpoint is a useful addition. No unnecessary words or repetition.
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?
Given the tool's simplicity and lack of an output schema, the description explains the return (presigned URL) and the key error (400). It doesn't mention the 403 error, but that is captured in the parameter schema. The tool's behavior is well-covered for an agent to call it correctly.
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%, so the parameter is fully documented in the schema. The description does not add new meaning to the parameter—it only restates 'company (NIF)' which is already covered. Baseline 3 is appropriate given the high schema coverage.
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 states a specific action ('Returns a presigned URL') with the resource ('representation PDF of a company (NIF)') and a key constraint (valid for 5 minutes). It clearly differentiates this from sibling tools like beel_generate_representation (which generates the document) and beel_get_representation (which likely fetches representation data) by focusing on the download mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to download the representation document) but does not explicitly mention alternatives or when not to use it. It provides useful context about signed vs unsigned documents and a 400 error, but lacks direct comparison to sibling tools or a 'use this over X' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description correctly adds value by disclosing the return shape (status, access_level, claim link, conditional company_id) and the scope 'you provisioned'. It provides useful behavioral context beyond the annotations without contradicting them.
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 compact and efficient, with the primary content in the first sentence and the endpoint in the second. There is no redundant or unnecessary text, and it is well-structured for quick agent consumption.
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?
For a simple GET operation with one parameter and rich annotations, the description covers the return contents and the scoping rule. It does not include error cases or authorization details, but these are not critical for a read-only tool with minimal complexity. Overall it is adequately complete.
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?
The schema has one parameter, account_id, with format uuid. The description only mentions it in the endpoint, providing no additional semantic detail. Since the parameter is self-explanatory and the description does not explicitly compensate for the 0% schema coverage, the baseline applies. The meaning is evident from the name and context, so a 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 description clearly states the verb 'Returns' and the resource 'one account you provisioned', and it lists the key fields returned. It distinguishes from the list tool by specifying a single account, and the name and description align well. It is clearly distinct from siblings like beel_get_by_id because it explicitly mentions account and its returned shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single account you provisioned, but it does not explicitly state when to use this instead of list_accounts or other getters. It does not provide exclusions or mention alternative tools. The guidance is inferred from the wording, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable context about error semantics (404 for both non-existent and non-owned events, preventing disclosure) and the content of the response (automatic invoicing outcome, stable failure code). This goes beyond the annotations and enriches the agent's understanding of 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 extremely concise and well-structured. The primary purpose is stated in the first sentence, followed by a clarification of error semantics, and ends with the endpoint. Every sentence earns its place, with no redundancy or fluff.
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?
For a simple read operation with annotations already covering safety, the description provides sufficient context: it explains what the response includes, how errors are handled, and the endpoint. A full output schema is absent, but the description fills key gaps. It could mention pagination or more detailed response structure, but that's not essential for a single-event retrieval.
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%, so all three parameters are well-documented in the schema. The description itself adds no parameter-specific details beyond what the schema provides. It does not clarify formats or relationships further, so it meets the baseline but does not elevate it.
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 states a specific verb ('retrieves') and resource ('a single payment event'), and details what is included (outcome of automatic invoicing and failure code). It clearly distinguishes from list and retry siblings by focusing on single-event retrieval. The endpoint is also provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like beel_list_payment_events or beel_retry_payment_event. It implies use when you have a specific event_id (schema notes it comes from list), but no explicit direction or exclusions are given. An agent might need to infer the appropriate workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, meaning the agent knows this is a safe, idempotent, read-only operation. The description adds the key behavioral fact that 'Nothing is persisted and no numbering is consumed,' which is a critical side-effect explanation beyond the annotations. It also warns about fiscal guardrails and refers to resources that affect outcome, adding context. There is no contradiction with annotations.
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?
The description is moderately sized and reasonably front-loaded with the main purpose. The first sentence clearly explains the function and non-persistence. The safety warnings are useful but are placed in a block with emoji and indentation, which is somewhat verbose and might be trimmed. Overall, each section contributes value, but it's not as tight as it could be—the endpoint line is redundant with the description and schema.
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?
Given the tool has 2 parameters, no output schema, and high-level annotations covering safety, the description covers the critical non-persistence behavior and references external guardrails. However, it doesn't describe the return value format or any potential errors beyond what the schema mentions for company_id. The reference to 'fiscal guardrails' is helpful but the description could be more complete by explicitly stating what the response contains (e.g., the invoice object with computed amounts/taxes). Still, it is reasonably complete for a read-only preview tool.
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 description coverage is only 50%: company_id has a detailed description (UUID, NIF, context derivation, 403 errors, non-disclosure), but recurring_invoice_id has no description. The description does not explain the format or semantics of recurring_invoice_id beyond the schema's UUID format. Since coverage is partial, the description could compensate by explaining what recurring_invoice_id refers to (the recurring template ID), but it does not. However, company_id's rich schema description carries most of the semantic weight, so the score stays above baseline but below perfect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the invoice that would be produced by the next generation of a recurring template, and explicitly notes nothing is persisted and no numbering is consumed. It differentiates from siblings like beel_generate_recurring_invoice_now (which likely generates/creates) by emphasizing the non-mutating preview nature. While it names the endpoint and operation, it doesn't explicitly contrast with all get_* siblings, but the core purpose is unambiguous.
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?
The description includes a caution to read fiscal guardrails before calling and points to two specific resources (beel://guardrails/invoice-types and beel://guardrails/regime-keys) along with a recommendation to call beel_docs_search for exhaustive rules. It implies this is a read-only preview and that it should be used when the caller wants to see the next occurrence without persisting. It does not explicitly list when not to use this tool versus alternatives, but the safety guidance and reference to docs provide a clear context for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context beyond these: it clarifies that the tax type catalogue is not company data and lives outside this resource, preventing confused assumptions. No contradiction with annotations; it complements them.
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 concise and front-loaded with the return value. Two short paragraphs plus an endpoint line contain only relevant information. The note about the external catalogue is useful and placed logically. No filler or redundant statements; the endpoint line is mildly redundant but harmless.
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?
Given the low complexity (one parameter, read-only operation), the description is complete for an agent to understand what the tool does and what it returns. The output is described (tax regime, percentage, key, IRPF, surcharge). Error behavior is covered in the schema parameter description. The only minor gap is the absence of a formal output schema, but the description suffices.
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 company_id parameter is documented thoroughly in the schema (including NIF derivation, 403 behavior, and the irrelevance of the BeeL-Active-Company header). The tool description adds no additional parameter-level detail, so the baseline of 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 description states exactly what the tool returns: the default tax regime with main percentage and regime key, plus IRPF and equivalence surcharge settings. The verb 'Returns' is specific and the resource is clearly 'tax configuration of a company (NIF)'. This distinguishes it from siblings like get_verifactu_configuration and update_tax_configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to fetch tax configuration) but does not explicitly contrast it with alternatives or state when not to use it. An agent can infer its purpose, but there is no direct guidance on when to prefer this over get_verifactu_configuration or when to use update_tax_configuration instead. No explicit exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a specific behavioral fact: the signing secret is never included in the response, which is valuable context beyond the annotations. No contradiction exists.
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?
Two sentences with no extraneous information. The core purpose is front-loaded, followed by a key behavioral note and the endpoint. Every element earns its place.
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?
For a simple read operation with rich annotations and full schema coverage, the description is sufficiently complete. It states what is returned, the secret exclusion, and the exact endpoint. The absence of an output schema and the simplicity of the parameters make further detail unnecessary.
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 descriptions cover 100% of parameters (account_id and webhook_id) with detailed explanations about ownership and 404 behavior. The description adds no additional parameter-level information, so the baseline of 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?
The description clearly states the verb ('Returns') and resource ('a single webhook subscription'), distinguishing it from list, create, delete, and patch operations. The additional note about the signing secret not being included further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description (retrieve a specific subscription by ID), but there is no explicit guidance on when to use this tool versus siblings like list or patch. The endpoint path implies the need for account_id and webhook_id, but no alternative routing is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations by explaining that invitations of all statuses remain in the list and framing the record as a trail of access grants. This is useful for understanding data permanence, though it does not touch on response format or pagination details.
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 two concise sentences plus the endpoint line. It leads with the main purpose, then adds one relevant detail about status retention. There is no filler, redundancy, or unnecessary explanation.
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?
For a simple read-only list operation, the description covers the essential purpose and the retention behavior. The schema documents parameters and pagination defaults, and annotations cover safety. While the missing output schema means the exact response shape is not disclosed, the description provides enough for an agent to understand it returns a list of invitations. Slightly more detail on pagination or returned fields would improve, but it is not critical.
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%, so page, limit, and account_id are already fully documented. The description does not add parameter-specific meaning beyond referencing account_id in the endpoint, which is redundant. With full schema coverage, the baseline of 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 description clearly states the action (lists), the resource (invitations sent to join the account), and explicitly notes that all statuses are included—accepted, revoked, and expired. This distinguishes it from sibling tools like beel_create_invitation, beel_get_invitation, and beel_delete_invitation, and the endpoint line further anchors its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what it does but does not explicitly mention when to use it versus alternatives or when not to use it. It does not reference beel_get_invitation for single pulls or beel_create_invitation for new invites, so an agent must infer the right context. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds behavioral details beyond that: it declares the entire list is returned and not paginated, and specifies the content (roles and granted companies). It also states the endpoint, reinforcing the operation's nature. No contradiction with annotations.
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 two sentences plus an endpoint line, with zero filler. The primary purpose is front-loaded, and each sentence adds distinct information: content returned, non-pagination behavior, and the HTTP endpoint. Efficient and well-structured.
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?
For a read-only list tool with one fully described parameter and no output schema, the description covers the essential operational details: what is listed, the lack of pagination, and the endpoint. The parameter description already handles error conditions (403). It does not describe the exact response structure, but that is not critical given the tool's simplicity and existing schema coverage.
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 coverage is 100% and the account_id description is already rich, explaining ownership, credential behavior, and 403 responses. The tool description does not add any parameter-specific meaning; it only restates the endpoint. With high schema coverage, the baseline is 3, and the description does not elevate it further.
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 states a specific action ('Lists the people with access to the account') and details the exact content ('account_role', companies/NIFs for MEMBERs). It also notes the endpoint and non-pagination, making the tool's purpose unmistakable. It clearly differentiates from a single-member fetch or grants-only tools by describing the full member list with role and grant information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context ('The whole list is returned; it is not paginated') that informs when to use it (when you need all members at once). However, it does not explicitly mention alternatives or exclusions, such as 'for a single member use beel_get_member' or 'for grants only use beel_list_member_grants'. Usage guidance is implied but not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness3/5
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.
Completeness4/5
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.
Parameters3/5
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.
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 — '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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry readOnlyHint=false, destructiveHint=false, idempotentHint=true, so the description is not required to restate those. It adds genuine behavioral context beyond them: PATCH partial-update semantics, the draft-only restriction, and the subtle series_id disclosure ('Changing series_id never moves the invoice to another NIF: a series of another company is not visible from here'). No contradiction with annotations — description's 'updates' aligns with readOnlyHint=false. Minor gap: no mention of response or VeriFactu side effects, but the bar is lowered by existing annotations.
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?
The description is compact and front-loaded: the first sentence states the core partial-update semantics, followed by the draft-only constraint, the series_id caveat, the endpoint, and pointers to guardrails/docs. Every sentence earns its place. The emoji-warning list is slightly stylistically noisy but functional and informative rather than padding.
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?
For a complex fiscal tool with an enormous inline schema (tax rules, VeriFactu, exemption sentinels, equivalence surcharges) and no output schema, the description provides strong orientation: partial semantics, draft-only scope, the series_id NIF edge case, the endpoint, and explicit pointers to beel://guardrails/invoice-state-machine and beel_docs_search for exhaustive rules. It wisely delegates the heavy detail to the schema and docs. Missing only a response-format note, which is minor given the delegation strategy.
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 description coverage is 67% (company_id and invoice_id are well documented inline, with a rich note on company_id as sole NIF context). The description adds value specifically for series_id, explaining it never reassigns to another NIF's series — semantics not present in the schema's series_id entry. The body parameter carries exhaustive inline documentation in the schema, so the description correctly leaves it to the schema. Genuine added value for the one parameter that needed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource with precise semantics: 'Updates only the fields present in the body, leaving every other field of the invoice as it is.' This clearly identifies a partial PATCH operation on a draft invoice and distinguishes it from a full replace/update. Sibling differentiation is implicit via the 'Only a draft invoice can be modified' constraint and the surrounding tool names (create_invoice, issue_invoice, void_invoice), but no sibling is named explicitly, so it stops short of a 5.
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?
The description gives clear when-to-use context: 'Only a draft invoice can be modified: an issued one is amended with a corrective invoice or voided.' This both scopes the tool and points to the alternative paths (corrective/void) for non-draft invoices. It also routes to beel://guardrails/invoice-state-machine and beel_docs_search for exhaustive rules. However, it does not explicitly name alternative tools by name (e.g., use beel_create_invoice to create a draft first), so guidance is context-rich but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds meaningful context: it advances the generation date and explicitly states 'Nothing is issued,' clarifying the non-destructive nature. It also warns about fiscal guardrails, which gives the agent behavioral context about regulatory implications. This goes beyond the annotations without contradicting them.
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 compact and well-organized: a one-sentence action summary, the endpoint, then a clearly separated guardrails warning. No redundant fluff; every sentence earns its place, and the most important information (what it does) is front-loaded.
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?
The tool is a simple skip operation with 3 parameters and no output schema. The description covers the action, the endpoint, and critical fiscal guardrails via pointer to resources. It does not describe the return value, but that may be acceptable given no output schema. The guardrails warning adds important context for safe usage, making the description reasonably complete.
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 67% (company_id and idempotency_key have rich descriptions, recurring_invoice_id lacks one). The description itself does not address parameters. The schema already handles most semantics, and the missing parameter is self-evident from the name and endpoint. The description adds no parameter-specific value, so the baseline of 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 description states a precise action ('Skips the next scheduled invoice generation') with the specific resource (recurring invoice) and a key consequence ('Nothing is issued'). It clearly distinguishes the tool's purpose from likely siblings like beel_generate_recurring_invoice_now, which would have the opposite effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to skip a generation) but does not explicitly say when to use this tool versus alternatives (e.g., generate now, set status). It includes a warning about fiscal guardrails and points to docs, but lacks explicit exclusion or alternative scenarios. Some context is provided, but no direct 'use this when' or 'instead of X' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only mark it as a non-read-only, non-destructive write operation), the description discloses the important partial-processing behavior: each product is handled independently, and rejected rows are reported while others are created. This adds significant context about failure handling and what to expect, which is valuable for an agent invoking the tool.
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 two sentences, front-loaded with the core action (create up to 100 products) and immediately followed by the key behavioral nuance (partial processing). It is efficient, contains no fluff, and includes the endpoint as a helpful reference. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a bulk creation with nested tax rules and many possible validations, the description covers the main operation and the partial failure mode but does not explain the structure of the report or how rejected rows are communicated, nor does it mention idempotency semantics (though these are in the schema). Since no output schema is provided, the description could have elaborated on the response, but the rich schema mitigates this gap. A 3 reflects that it is adequate but not fully complete.
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?
The description does not add parameter-level meaning beyond the schema; it only mentions 'NIF' which is already described in the company_id parameter. With schema description coverage at 67%, the schema already documents most parameters (including nested objects like TaxInfo with detailed rules), so the description does not need to repeat them. A 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 description clearly states the action: 'Creates up to 100 products in the catalog of this company (NIF)' and provides the endpoint. It distinguishes this bulk creation from the single create by specifying the capacity and the partial-processing behavior, which is a unique trait. It is not a tautology and gives a concrete resource and scope.
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?
The description implies its usage for bulk product creation with a clear limit (up to 100) and explains the partial processing, which indicates when it would be appropriate (many products at once). However, it does not explicitly name alternatives like the single-product creation tool or state when not to use it, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds meaningful behavioral detail beyond that: the generation cadence (monthly on day_of_month), the start_date past-acceptance behavior with no back-dating, and explicit warnings about fiscal guardrails. It also mentions the endpoint for clarity. While it does not detail return format or rate limits, it substantially improves on the annotations' limited disclosure.
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?
The description is structured and front-loaded: it opens with the core purpose, then covers the start_date nuance, endpoint, and guardrails in a logical order. It uses bullet-style pointers for fiscal rules and ends with a pointer to exhaustive docs. While it includes some redundancy (e.g., the start_date nuance appears in schema too), it is concise for the complexity and not padded.
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?
For a tool with many parameters and complex fiscal rules, the description covers the essential behavior: what it creates, how recurrence works, the start_date edge case, and critical guardrails with pointers to resources. It does not mention idempotency behavior (but schema covers it) or output format, but given the schema richness and the presence of a docs pointer, it is sufficiently complete for an agent to invoke it adequately.
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 67%, so the schema already documents many parameters (start_date, frequency, verifactu_enabled, idempotency_key, etc.). The description reinforces the start_date behavior but adds little beyond the schema's own parameter descriptions. It does not explain the flat tax fields (handled in schema) or otherwise compensate for undocumented parameters. This is at the baseline for good schema coverage.
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 clearly states the verb ('Creates'), the resource ('recurring invoice template'), and the scope ('under this company (NIF)'). It also specifies the key components (template data, recurrence) and explicitly contrasts with direct invoice creation by mentioning 'template' and 'recurrence'. This distinguishes it from siblings like beel_create_invoice and beel_create_recurring_invoice_derivation without needing to inspect schemas.
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?
The description explains when to use it (to set up a recurring invoice template) and includes a critical usage nuance: past start_dates are accepted but never back-generate. It also directs to guardrails and documentation for deeper rules. However, it does not explicitly state when NOT to use it or name alternative tools (e.g., beel_generate_recurring_invoice_now for immediate generation), so the 'when not' part is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description elaborates on the idempotentHint annotation by explaining that an unscheduled invoice still returns 204, and specifies the result ('returning it to a plain draft'). It also warns about fiscal consequences and references dedicated guardrail resources, adding significant behavioral context beyond the annotations. It does not contradict the annotations.
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?
The description is compact and well-structured, with the core behavior front-loaded, followed by idempotency and the contrast with PUT, an endpoint reference, and a clearly marked warning section. The warnings and doc pointer are valuable for a fiscally sensitive operation, though they add length. Overall, it is efficient without unnecessary fluff.
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?
The description addresses the key decision points: idempotency, feature requirements, and fiscal dangers, and points to the docs for exhaustive rules. It does not detail all possible error responses (e.g., invoice not found), but given the idempotent nature and the guardrail references, the coverage is sufficient for an agent to call it correctly.
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 descriptions for both parameters are comprehensive, covering 100% of the parameters with detailed explanations (e.g., company_id semantics and 403 behavior). The description itself adds no extra parameter-level information, so the baseline of 3 applies given the high schema coverage.
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 states a specific action: 'Removes the scheduling of an invoice, returning it to a plain draft.' It clearly distinguishes itself from the sibling PUT operation ('Unlike the PUT, it does not require the scheduled_invoices feature') and from deletion, making the purpose unambiguous.
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 contrasts directly with the PUT (beel_set_invoice_schedule) and explains a key condition (no feature requirement). It also references fiscal guardrails and directs to beel_docs_search for exhaustive rules. However, it does not explicitly mention alternative actions (e.g., when to use delete_invoice or void_invoice) or provide a 'when not to use' statement beyond the PUT comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, and destructive=false. The description adds valuable behavioral context beyond annotations: the `company_id` is the only source of context (BeeL-Active-Company header is ignored), and the 403 response for both unreachable and non-existent NIFs to avoid existence disclosure. This is meaningful behavior disclosure that the annotations do not cover.
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?
The description is well-structured with a clear purpose statement, an exclusion note, an endpoint reference, and a guardrail section. It is a bit long but every section earns its place, and the key purpose is front-loaded. The use of bullets and pointers to docs keeps it focused.
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?
For a simple read operation with one parameter, the description covers what is returned, what is not returned, how to get the missing data, and points to guardrails for context selection. It does not describe the exact response schema, but that is not required given no output schema and the low complexity. The description is comprehensive enough for an agent to call it correctly.
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?
The schema description coverage is 100% and the single parameter `company_id` is already fully explained in the schema: it is the NIF, it derives the owning account, and it details how it plays in context and error responses. The tool description adds no additional parameter semantics beyond referencing the guardrails. The baseline of 3 applies since the schema does the heavy lifting.
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 states a specific verb ('Returns') and resource ('company (NIF)') and enumerates the exact data returned: fiscal data, activation state in Test and Live, and VeriFactu registration state. It also explicitly excludes invoice series, distinguishing it from sibling get/list tools. This is a precise purpose with clear differentiation.
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?
The description clearly states that invoice series are not part of this response and points to the correct endpoint for them (`GET /v1/companies/{company_id}/series`). It also references 'Fiscal guardrails' and directs users to `beel_docs_search` for exhaustive rules. While it doesn't explicitly name an alternative tool, the endpoint reference and exclusion are sufficient for most usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant context: the body is fetched live, availability depends on provider retention, `body_available`/`html_body`/`text_body` behavior, and the QUEUED/REJECTED edge case. This goes beyond the annotation set without contradicting it.
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 tightly structured: a single-sentence summary of return content, a concise caveat about body availability, and an endpoint line. Every sentence adds value, and it is front-loaded with the core purpose. No filler or redundancy.
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?
For a read operation of moderate complexity, the description covers all essential aspects: the returned data, conditional body availability, and the statuses that preclude a body. With no output schema, the description sufficiently explains what an agent can expect. The endpoint is a helpful extra. Nothing critical 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?
The input schema already covers both parameters with detailed descriptions (email_id, account_id including 403 semantics), so schema coverage is 100%. The tool description does not add parameter-specific meaning beyond what the schema provides; it only references the parameters indirectly via the endpoint. Baseline of 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 description opens with a specific verb ('Returns') and a precise resource ('one recorded email'), enumerating the returned data (body, attachments, invoices for batch emails). This clearly distinguishes it from siblings like beel_get_email_delivery_indicators (which presumably returns indicators) and beel_list_email_deliveries (which lists multiple).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single email's details and explains when the body may be unavailable (QUEUED/REJECTED), but it does not explicitly state when to choose this tool over its siblings, such as beel_get_email_delivery_indicators or beel_get_email_delivery_indicators. No alternatives or exclusions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds crucial behavioral context: that revoked, expired, and accepted invitations remain readable because they are a trail, and that revoking does not erase the record. This goes beyond the annotations and helps the agent understand non-obvious semantics.
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 concise: two sentences that front-load the primary purpose and then add the lifecycle nuance, followed by the endpoint. No redundant or extraneous information is present.
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?
As a simple get-by-ID operation, the description covers the essential purpose and behavioral characteristic (lifecycle). The lack of an output schema is mitigated by the note that it matches the list shape. The only minor gap is that 'invitation_id' is not elaborated, but the field name and overall design make it obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% ('account_id' has a description, 'invitation_id' does not). The tool description does not add any explanation for 'invitation_id', leaving the agent to infer its format and purpose. Since schema coverage is low, the description should have compensated, but it does not.
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 states a specific verb ('Returns') and resource ('one invitation of the account') and clarifies that it returns the same shape as the list, including lifecycle statuses. This clearly distinguishes it from list operations and other tools, and the mention of lifecycle makes it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like 'beel_list_invitations'. The purpose is inferable from the name and the phrase 'one invitation', but there is no direct guidance on selecting this over listing all invitations or when the invitation_id is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds helpful context that customization is per-NIF and that the account is derived from company_id, reinforcing the open-world nature. It does not contradict annotations. However, it does not disclose additional behaviors beyond the annotations and the parameter details, which are already extensive in the schema. The description contributes modestly but not substantially beyond the annotation coverage.
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 concise and well-structured: it front-loads the primary purpose, clarifies the per-NIF scope, points to the related options endpoint, and gives the exact HTTP endpoint. Every sentence adds value with no redundancy. The length is appropriate for the tool's complexity.
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 adequately lists the returned fields (PDF template, accent colour, invoice language, email language, current logo) so the agent knows what to expect. It also provides the endpoint and references the options endpoint for additional context. The parameter description covers error conditions. The tool is a straightforward read operation, and the description combined with annotations and schema fully equips the agent to call it correctly.
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 parameter 'company_id' already has a rich description explaining its role, the derivation of the account, the irrelevance of the BeeL-Active-Company header, and 403 error behavior. The description adds the fact that customization is per-NIF, which is informative but does not significantly augment parameter meaning beyond what the schema already provides. This aligns with the baseline of 3 for high schema coverage.
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 clearly states the verb 'Returns' and the resource ('how the invoices of a company are rendered and delivered') and enumerates the specific data returned: PDF template, accent colour, invoice language, email language, and current logo. It also distinguishes this from related tools by noting that the catalogue of templates is served by a separate endpoint, effectively differentiating it from list/option tools. This is specific and unambiguous.
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?
The description implies usage by stating what the tool returns, and it refers to the alternative endpoint for obtaining the catalogue of templates and suggested colours. It does not explicitly name the sibling tool 'beel_list_invoice_customization_options', but the reference to the endpoint guides the agent. However, it lacks a direct contrast such as 'Use this for per-NIF customization; use the options endpoint for the available templates.' Overall, the context is clear but exclusions and explicit alternatives are not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds valuable behavior: the image is generated and cached on first request, so later calls return cached images; the URL expires in five minutes; and only GET is allowed. This goes beyond the annotations and helps the agent understand caching and expiry implications. The endpoint is also provided, which aids debugging and understanding. No contradictions.
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?
The description is concise and front-loaded with the key info: what it returns, the format, and the purpose. The endpoint is appended. There is minimal redundancy, though the endpoint could be considered extra but useful. The description is not overly verbose and avoids filler.
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?
Given the tool's simplicity, the description covers the essential aspects: purpose, output type, caching behavior, URL expiry, and HTTP method restrictions. It does not mention what happens if the invoice doesn't exist or is not accessible, but annotations and schema cover some error behavior. The output schema is absent, so the description does not need to describe return values. Overall, sufficiently complete for an agent to call correctly.
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 coverage is 100%, so the description does not need to detail parameters. However, the description does not add extra semantic value beyond what the schema already provides. The schema for company_id is already detailed (explaining the NIF context, auth, and 403 behavior). The description simply mentions the endpoint, which is redundant with the schema's param names. Thus, the description adds no incremental value for parameters; 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 description states a clear purpose: returns a temporary pre-signed URL to a preview image (WebP) of an invoice for inline rendering. It includes the endpoint, distinguishing it from related tools like beel_get_invoice_pdf and beel_download_representation_document. It clearly names the resource and the specific output type, leaving no ambiguity about what the tool does.
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?
The description implies usage for inline preview rendering and notes that the URL is only for GET. It does not explicitly compare with alternatives like beel_get_invoice_pdf, but the mention of 'preview image' and 'inline rendering' gives clear context. The sibling list includes get_invoice_pdf, so a brief comparison would be helpful, but the context is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context beyond that: it explains pagination ('paginated list', 'pagination envelope'), the semantics of the q parameter (matches name, code, description), and the privacy behavior of company_id (403 for non-existent NIF, no disclosure). This is exactly the kind of context annotations do not provide.
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?
The description is efficiently written with three sentences (plus endpoint). It is front-loaded with the primary purpose, then adds search behavior and endpoint. There is no redundant repetition of schema details. It could arguably omit the withdrawn search mention, but that adds useful historical context. Overall, it earns its place.
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?
Given the complexity (12 parameters, enums, pagination), the description covers the core: purpose, search behavior, company_id context derivation, and endpoint. It does not specify the exact response structure, but since there is no output schema and it's a simple paginated list, that may be acceptable. The mention of the withdrawn search endpoint further enriches context. Slightly more could be said about filter behaviors (e.g., how filters combine), but schema covers that.
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 each parameter has a description. The tool description adds minimal parameter-specific semantics—it slightly enhances q by noting 'no separate search path' and clarifies pagination envelope, but these are already implied by the schema (q description says 'Search by name, code or description'). The schema itself is thorough, so the description does not need to compensate. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Returns a paginated list of the products/services of this company (NIF), with optional filters.' It specifies the resource (products/services) and scope (company NIF), and provides the endpoint. However, it does not explicitly differentiate from other list tools in the sibling set (e.g., beel_list_customers, beel_list_invoices), though the resource is unambiguous.
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?
The description explicitly directs usage for search: 'Searching is `?q=` on this collection: there is no separate search path.' This prevents an agent from seeking a separate search tool. It also clarifies the behavior of company_id (deriving context and 403 semantics), which is essential for correct usage. It does not enumerate alternative tools but provides clear situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it states that each attempt records the response it got and that retried events appear once per attempt, which clarifies the data semantics beyond what annotations provide.
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?
The description is concise, front-loading the main purpose and then providing filtering hints. It includes the endpoint URL, which is somewhat redundant given the tool name and schema but not harmful. Each sentence serves a purpose, and there is no unnecessary flourish.
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?
The tool has no output schema, but the description provides enough context about the return content (each attempt with response, newest first). It covers key behavioral aspects such as retry duplication and filtering options. Pagination is handled in parameter descriptions, and error states are explained in the schema for account_id and webhook_id. Overall, it is complete for a list operation, though it could detail the exact response structure if needed.
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?
The input schema has 100% coverage with detailed descriptions for all parameters, including security-related notes for account_id and webhook_id. The tool description adds only a minor hint about using event_id to follow a single event, but this is essentially captured in the schema's description for event_id as well. The description does not significantly enhance parameter understanding beyond the schema.
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 clearly states the tool returns delivery attempts of a subscription, using the verb 'Returns' and specifying the resource. It differentiates from siblings like beel_list_webhook_subscriptions (which lists subscriptions) and beel_retry_webhook_delivery (which retries), and explains that retried events appear as multiple attempts, providing distinct behavioral variance.
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?
The description provides explicit guidance on narrowing results with event_type or event_id, and explains that event_id is used to follow a single event across attempts. However, it does not explicitly mention alternative tools or when not to use this one, though the context implies it for listing delivery attempts versus retrying or listing subscriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds substantial behavior: it immediately resends the original payload, records a new delivery entry while keeping the original, and emphasizes that the payload is the one captured at event time (not a fresh snapshot). This goes well beyond annotations, clarifying side effects (new entry) and the snapshot nature. No contradiction with annotations.
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?
The description is two clear sentences plus an endpoint line. It front-loaded the primary action ('Re-sends the original payload') and adds the key nuance about the payload being original. Every sentence adds value without filler; however, it could be tightened by integrating the endpoint into the first sentence, though it remains appropriately concise and well-structured.
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?
The description explains the core behavior, side effects, and payload semantics, which is complete for a retry action. It omits explicit usage guidance vs. alternatives (covered under usage_guidelines) but schema descriptions already handle error codes and idempotency. No output schema exists, so no return-value explanation is needed. The only gap is the lack of explicit 'when to use vs. siblings', but overall the definition is nearly complete.
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 each parameter in the schema already carries detailed semantic descriptions (e.g., account_id explains 403 behavior, webhook_id explains 404, idempotency_key explains blind retry vs. collision). This description does not add any parameter-specific information beyond what the schema provides; it relies entirely on the schema. Baseline 3 is appropriate because schema does the heavy lifting and description adds nothing extra for params.
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 states a specific verb ('re-sends the original payload') and resource ('a delivery'), and clarifies its scope precisely. It distinguishes itself from siblings like beel_retry_payment_event (different resource) and beel_test_webhook_subscription (test vs. actual retry) by focusing on delivery retry with retained original entry. The action is unambiguous and unique 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and its payload behavior, but does not explicitly mention when to use it over alternatives (e.g., beel_retry_payment_event or beel_test_webhook_subscription). There is no 'use this when...' guidance or exclusions. The context implies usage for replaying a failed delivery, but the dimension requires explicit alternatives or conditions; this is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as non-read-only, non-destructive, and idempotent. The description adds valuable context: it requires a feature flag, it replaces scheduling regardless of prior existence, and it explains the two generation modes with their consequences (e.g., DRAFT leaves for review, ISSUE_AND_SEND auto-issues). It also warns about fiscal guardrails and points to a state-machine resource. This exceeds the baseline despite existing annotations.
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?
The description is well-structured: purpose first, then modes, prerequisites, endpoint, and guardrails. Each sentence earns its place, though the guardrails section is slightly verbose. Overall it is front-loaded and scannable, making it easy for an agent to extract the key facts quickly.
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?
For a tool with 3 parameters, no output schema, and annotations covering idempotence and non-destructiveness, the description covers the essential behavioral rules: replacement semantics, generation modes, date constraint, feature requirement, and fiscal guardrails. It points to docs for exhaustive rules. The only missing context is the return value or error specifics, but with no output schema and the schema describing company_id behavior, this is sufficient for correct invocation.
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?
The schema already provides strong descriptions for company_id (NIF behavior, 403s) and body (both fields required, no default rationale). The tool description reiterates the generation_mode semantics and date constraint, but adds little beyond the schema—except the explicit 'Both fields are required' note and the rationale for no default. With schema coverage at 67%, this is a solid baseline 3; the description doesn't meaningfully augment parameter meaning.
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-resource pair: 'Replaces the scheduling of a draft invoice, whether it had one or not, moving it to SCHEDULED.' This clearly distinguishes the tool from siblings like beel_get_invoice_schedule and beel_delete_invoice_schedule, and explains the effect on the invoice state. The two generation modes are also detailed, so an agent can select it with confidence.
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?
The description clearly states the tool's purpose (replacing scheduling) and the prerequisite feature (scheduled_invoices). It does not explicitly name sibling alternatives for exclusion, but the context is unambiguous: this is the setter, versus get/delete for schedule. The pointer to beel_docs_search for exhaustive rules is helpful for edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the bar is lower. The description adds meaningful behavioral context by specifying that only the targeted company grant is revoked and other grants remain untouched, which goes beyond the generic destructive annotation.
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 compact and front-loaded: the first sentence states the primary action and scope, the second adds the boundary condition, and the endpoint line provides reference without fluff. Every sentence earns its place.
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?
For a simple 3-parameter destructive action with strong annotations and fully documented parameters, the description is nearly complete. It could optionally state what happens if the grant does not exist or what response is returned, but for a straightforward single-grant revocation, the provided information is sufficient.
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%, so the input schema already fully documents all three UUID parameters. The description itself adds no parameter-level detail, which is acceptable given the schema carries the burden. 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 description uses a specific verb ('Revokes') and names the exact resource and scope: a MEMBER's access to one company. It also clarifies what is NOT affected (grants over other companies), which distinguishes it from related sibling tools like beel_delete_member or beel_put_member_grant.
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?
The description clearly implies when this tool is appropriate: when you need to remove a member's grant for a single company while preserving their other grants. It does not explicitly name alternatives like beel_delete_member for full removal, but the scope statement effectively excludes that use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: it communicates the lifecycle status transitions (PROVISIONED → CLAIMED → ACTIVE), the inclusion of access_level and claim link state, and that results are 'Newest first'. This meaningfully enriches the agent's understanding of what the call does and how results are ordered.
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 compact—two sentences plus an endpoint line—and front-loaded with the most important information (what it returns, lifecycle status). Every sentence adds value: the return fields, ordering, filtering options, and endpoint. No fluff or redundancy.
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?
Even though there is no output schema, the description explains the key returned fields (status, access_level, claim link state) and the ordering. It does not explicitly mention pagination (cursor/limit) behavior in the description, but the schema covers those parameters. For a list operation, the description is largely complete, though a mention of pagination would make it flawless.
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 documentation covers 75% of parameters, with detailed descriptions for limit, cursor, status (enum with lifecycle explanation), and external_ref. The description repeats that status and external_ref can be used to narrow/filter, but adds no new meaning beyond the schema. Since coverage is high, the description does not need to compensate much, so 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 description clearly states a specific action ('Returns the accounts you provisioned') and specifies exactly what is returned (lifecycle status, access level, claim link state). It is clearly distinct from list_* siblings like beel_list_customers or beel_list_invoices because it is explicitly about provisioned accounts, and from beel_get_account which is presumably a single-account fetch.
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?
The description provides concrete filtering instructions: 'Narrow the list with `status`, or look one up by the `external_ref`'. It gives clear context for when to use parameters, but does not explicitly compare to alternative tools (e.g., 'use get_account for a single account'), so it's not fully explicit about alternatives. Still, the usage context is clear enough for parameter selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's job is reduced. It adds beyond that by explaining the empty result for OWNER/ADMIN and the endpoint format, giving context about the operation's behavior that annotations do not cover.
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?
Two economical sentences plus the endpoint line. The core purpose is front-loaded, and the OWNER/ADMIN exception is concisely stated without redundancy. Every clause earns its place.
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?
For a read-only list operation with well-documented schema and annotations, the description conveys the essential purpose, the special case for OWNER/ADMIN, and the endpoint. It does not mention pagination or response format details, but for this simple list tool, those are minor omissions.
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?
The input schema fully covers both parameters (account_id and member_id) with descriptions, so baseline is 3. The description does not add parameter-specific details, but it does hint at the output structure (companies and access levels), which is not directly about parameters.
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 (Lists), a clear resource (companies/NIFs granted to a member), and the returned attribute (access_level). The description also distinguishes this read operation from mutation siblings like beel_put_member_grant and beel_delete_member_grant by its read-only nature.
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?
Provides a valuable usage hint: for OWNER and ADMIN it returns empty because they implicitly reach all companies, so an agent knows when this tool adds value and when it will return nothing. It does not explicitly mention alternative tools, but the special-case note guides effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond annotations: Test and Live connections are independent, results are filtered by the mode of the key used, and a NIF with no connections returns 200 with an empty list. This enriches the agent's expectations materially.
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?
Three information-dense paragraphs with the core purpose and return-shape front-loaded, followed by the key mode caveat and a reference endpoint line. The endpoint line is slightly redundant given the tool name, but it is short and provides useful HTTP context; there is no wasted prose.
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?
For a single-parameter, no-output-schema list tool whose safety profile is fully covered by annotations, the description is complete: ownership scope, status field, empty-list behavior, mode independence, and the endpoint. Nothing an agent needs to call it correctly or interpret its result 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?
Schema description coverage is 100%, and the single parameter company_id already carries a rich definition explaining context derivation, the BeeL-Active-Company header's irrelevance, and the 403/404-equivalent behavior. With the schema doing this heavy lifting, baseline 3 applies; the description adds only marginal value on top, reinforcing the owns-or-manages scope that the schema also mentions.
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 precise verb and resource ('Returns the payment provider connections of a NIF'), scopes it ('your account owns or manages'), and names what each result carries (provider-side account, status). The empty-list-200 behavior further pins down semantics, and it is clearly distinguished from lifecycle siblings beel_initiate_payment_connection and beel_disconnect_payment_connection by describing a read-only listing.
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?
Gives an explicit intended use ('Use it to check whether a NIF you provisioned has completed its connection') and the empty-list interpretation. It does not name sibling alternatives or state when not to use it, but the surrounding connections lifecycle makes the read-only role inferable; the Test-vs-Live mode caveat is a valuable operational guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses significant non-obvious behavior: the exclusion of drafts/proformas, the separate counting of rectifying invoices, the conditional counting of voided invoices, and the non-monotonicity that makes it unsuitable as a cursor. This is valuable context that annotations cannot convey.
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 two tight paragraphs: the first front-loads the core purpose and counting rules, the second explains the non-monotonic caveat and gives the endpoint. Every sentence earns its place; no filler or redundancy.
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?
Given there is no output schema, the description explains the key semantics (count, last_invoice_at, exclusions) and the endpoint. However, it does not describe the response structure (e.g., array of objects with NIF, count, and last_invoice_at fields) or pagination behavior. This is a minor gap since the core information needed for correct usage is present.
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 schema itself already provides a detailed explanation of account_id (including authorization scope and error semantics). The tool description adds nothing about parameters, so the 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 description states a specific verb ('Returns') and resource ('for each company (NIF) of the account, how many fiscal documents it has issued and when it last issued one'), and clarifies exclusions (drafts, scheduled invoices, proformas). It distinguishes itself from siblings like beel_list_invoices and beel_get_fiscal_summary by focusing on per-company document counts, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage caveat (not usable as a synchronization cursor due to non-monotonic count) and explains the counting rules, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No sibling tools are named as alternatives, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it lists both active and inactive subscriptions, clarifies that all account members see the same list (authorship != visibility), and states that signing secrets are never included. These details help an agent understand side effects and response contents without contradicting any annotation.
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 two concise sentences plus an endpoint line, with zero filler. It front-loads the primary purpose, then adds two high-value clarifications (active/inactive, visibility, no secrets). Every sentence earns its place, making it easy to parse quickly.
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?
For a read-only list tool with three params and no output schema, the description is largely complete. It explains what is returned (subscriptions), the scoping (account in path), and critical exclusions (signing secrets). The schema covers pagination details. However, it does not explicitly describe the response shape (e.g., an array of subscription objects), which an agent might need to know, though the absence of an output schema makes this less critical. Overall, it is sufficient for correct invocation.
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?
The input schema already provides 100% description coverage for all three parameters, including detailed semantics for account_id (scope determination, error codes) and pagination params (defaults, echoing in response). The description only restates the account in the path via the endpoint line, adding no new meaning beyond what the schema already documents. Baseline 3 is appropriate per the rubric.
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 clearly states the tool returns webhook subscriptions for an account, explicitly including both active and inactive ones. It goes beyond a simple verb+noun by clarifying scoping ('of the account in the path') and visibility semantics ('every member sees the same list'). The endpoint line further specifies the HTTP call, leaving no ambiguity about what the tool does.
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?
The description gives clear context about what the tool does (lists all subscriptions for an account) and clarifies behavioral nuances like shared visibility and omission of signing secrets. However, it does not explicitly contrast with related tools such as beel_get_webhook_subscription (singular fetch) or beel_list_webhook_deliveries (deliveries), so an agent might not immediately know when to choose this over those. The context is strong but lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false), lowering the burden. The description genuinely adds behavior beyond that: the PATCH partial-application rule, the critical distinction that a null clears a field whereas omitting keeps it, and the warning that no PUT exists so omitted fields are never wiped. It does not contradict any annotation.
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?
Three crisp paragraphs, each earning its place: the core update semantics are front-loaded first, the canonical-usage context second, and the endpoint reference last. No filler, no repeated annotation content, and the most error-prone detail (null clearing) is surfaced immediately.
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?
For a subtle partial-update operation, the description covers the essential high-level semantics (touch-only, null-clears, no PUT) while the rich input schema carries field-level validation, AEAT checks and VeriFactu rules. No output schema exists, so return-value explanation isn't owed. A minor gap: it never flags the sibling relationship to beel_create_customer/beel_delete_customer, but the core needed context is present.
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 coverage is 67%, and the schema's $defs are exceptionally rich (PatchCustomerRequest documents the null-clear rule per field, company_id explains the 403/disclosure behavior). The description reinforces the null-vs-omit idea and points 'see PatchCustomerRequest', but it does not add parameter meaning the schema doesn't already convey, so it sits at the baseline.
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 first sentence states a specific verb and resource ('Updates only the fields present in the body... of the customer') and pins down the exact semantic: partial update with omitted fields untouched. It distinguishes itself from the hypothetical full-replacement PUT and is clearly distinguishable from siblings like beel_create_customer and beel_get_customer without opening a schema.
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?
'This is the canonical way to edit a customer' is explicit and actionable, and naming the non-existent PUT ('which would clear the fields you omit') preempts the agent from looking for a full-replacement route. It stops short of contrasting against the generic beel_patch_by_id sibling or stating when create/delete are preferable, so it loses a point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavioral traits: the old secret is immediately invalidated and the new secret is returned only once. These are not derivable from annotations and are essential for correct invocation.
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 three concise sentences plus an endpoint line, all directly useful. The purpose is front-loaded, followed by two critical operational warnings; no superfluous content exists.
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?
For a mutation with no output schema, the description covers the essential caveats: invalidation timing, single-return of new secret, and the need to update verification logic. It does not describe the response format, but that is less critical given the operation's simplicity and the strong schema coverage.
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% for all parameters (account_id, webhook_id, idempotency_key), and the description adds no parameter-specific meaning. It correctly relies on the schema for parameter semantics, which is the baseline for high coverage.
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 'Generates a new HMAC secret for a webhook subscription,' a precise verb+resource statement that clearly differentiates from sibling tools like create_webhook_subscription, patch_webhook_subscription, or delete_webhook_subscription. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its purpose but does not explicitly contrast with alternatives or state when not to use it. It does provide operational guidance ('update your signature verification logic before rotating'), which is valuable context, but it lacks explicit when-to-use vs. sibling routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a mutation (readOnlyHint: false), idempotent, and non-destructive. The description adds useful behavioral context by specifying exactly what the language affects (interface, template names/colours, emails) and what it does NOT affect (per-company invoice/email languages). This goes beyond the annotation hints and clarifies side effects without contradiction.
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 three sentences with no filler. It front-loads the core purpose, then explains scope, then adds the endpoint. Every sentence carries useful information and the formatting is clean.
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?
For a simple tool with one parameter, no output schema, and annotations already covering idempotency and safety, the description is quite complete. It covers the purpose, the parameter's effect, scope limitations, and the endpoint. Minor omissions like response format or timing are not critical for correct invocation.
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?
The schema describes the 'language' parameter with an enum (es, en, ca) and 0% schema_description_coverage means the description does not describe parameters directly. The description does mention the parameter name and its role, but does not list allowed values or defaults, relying on the schema for that. It adds minimal value over the schema, so a 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 description states a specific verb ('Updates'), a clear resource ('preferences of the authenticated person'), and names the exact mutable preference ('language'). It also distinguishes itself from siblings by explicitly scoping to personal preferences rather than company or fiscal-profile settings, an important differentiator given the large tool list.
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 the scope of the language preference (interface, templates, colours, emails) and clarifies that it belongs to the person, not to a fiscal profile, which tells the agent when this tool applies versus per-company settings. However, it doesn't explicitly name alternative tools or give an explicit 'when not to use' statement, relying on the scope description to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already show readOnlyHint=false), the description discloses atomicity, the exact HTTP status codes per mode (422 for validation failure, 200 for dry run, 201 for real run), the validation scope (AEAT register, duplicates, field formats), and that both modes return the same per-record report. It also clarifies the `company_id` as the sole source of context and that a non-existent NIF returns 403 — all useful behavioral context the annotations do not cover.
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?
The description is structured with clear headers, bullet points, and a warning callout. It front-loads the core purpose and the atomic semantics, then expands into modes and guardrails. While longer than the ideal, every sentence earns its place; there is no redundancy or fluff.
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?
Given the rich input schema (which includes all field details) and the absence of an output schema, the description covers the operation's behavior, modes, validation rules, and points to external documentation for exhaustive details. It mentions the per-record report but does not describe its structure; that minor gap is acceptable as the schema already covers inputs and the report format is not critical for invocation correctness.
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 75% and the schema itself has very detailed parameter descriptions (e.g., `company_id`, `dry_run`, `idempotency_key`, and the nested customer schema). The description adds the atomicity and validation behavior but does not clarify parameter meaning beyond what the schema already provides. It does not need to, but it also does not add significant value on top; hence baseline 3.
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 states a specific verb ('Creates'), a precise resource ('customers of this company (NIF)'), and adds a clear bound ('up to 500'). It unambiguously distinguishes this bulk tool from the single-create sibling `beel_create_customer` and from other bulk tools like `beel_create_products_bulk`.
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?
The description explains the two operational modes (`dry_run` vs. `dry_run=false`) and when each is appropriate, and explicitly directs the agent to `beel_docs_search` for exhaustive rules. It does not explicitly contrast with sibling tools, but the 'bulk' and 'up to 500' phrasing makes the use case obvious. Missing an explicit 'use this instead of X' but strong enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read, non-idempotent, non-destructive operation. The description goes beyond these by warning that the signing secret is returned only once, the 10-subscription cap, and the duplicate-subscription behavior. These are critical behavioral traits not captured in the schema or annotations, and they are clearly disclosed.
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?
The description is efficient, with each sentence earning its place: purpose, secret warning, limits, and endpoint. It is front-loaded with the core action and then critical caveats. Slightly longer than necessary but without fluff.
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?
For a creation tool with no output schema, the description covers the unique aspects: one-time secret, subscription limits, duplicate behavior, and endpoint. It doesn't detail the response envelope or idempotency behavior, but those are partially covered by the schema. The description is complete enough for an agent to correctly invoke the tool and understand consequences.
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?
The input schema already provides detailed descriptions for parameters (url, events, account_relationship, account_id, idempotency_key), and schema coverage is high. The description adds minimal parameter-specific information beyond mentioning 'events' and the account limit; it mainly adds operational context rather than parameter semantics. Baseline of 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 description states a specific action ('Registers an HTTPS endpoint to receive event notifications'), identifies the resource (webhook subscription), and gives the exact HTTP endpoint. It clearly differentiates from sibling tools like beel_get_webhook_subscription or beel_delete_webhook_subscription by focusing on creation.
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?
The description provides clear context for using this tool, including the one-time nature of the signing secret, the 10-subscription limit, and the duplicate behavior for repeated URLs. It doesn't explicitly mention alternatives like updating or deleting subscriptions, but the usage context is strong and sufficient for an agent to decide when to create a subscription.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by specifying exactly what changes (future invoices lose logo) and what remains unchanged (already issued documents). It also discloses idempotency (204 on absent logo). Annotations only indicate destructiveHint; the description adds concrete behavioral detail without contradiction.
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?
Two concise sentences plus the endpoint line deliver all necessary information with no redundancy. The main purpose is front-loaded, and the idempotency note is efficiently appended.
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?
For a single-parameter tool with no output schema, the description covers the key behaviors: effect on invoices, idempotency, and the 204 status. The schema parameter details handle authorization and error cases. Nothing critical is missing for correct usage.
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?
The input schema already provides a thorough description of `company_id` (ownership derivation, 403 behavior, privacy). Since schema coverage is 100%, the description adds no additional parameter semantics beyond the endpoint reference, so a baseline of 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 description clearly states the action ('removes the logo') and the target ('of a company (NIF)'), with a specific endpoint. It distinguishes this from the many other delete tools by focusing on the logo-specific operation, and adds behavioral context about invoice effects.
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?
Provides clear context on the operation's effects (future invoices without logo, past unchanged) and idempotent behavior (204 on absent logo). It does not explicitly compare to alternatives or state exclusions, but there is no obvious sibling for logo deletion, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint: true, idempotentHint: true), the description discloses that it's a soft-delete, that the code is not released, that it can return 409 SERIES_CODE_DUPLICATED on recreation, and that it can leave a type with no series. It also points to fiscal guardrails and the endpoint. This enriches the annotation info without contradicting it.
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?
The description is logically structured: core action, conditions, endpoint, fiscal guardrails, and a pointer to exhaustive docs. It front-loads the main purpose and avoids redundancy. It is a bit long but each sentence earns its place, and the closing pointer keeps it from over-expanding.
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?
Given the complexity (delete with preconditions, failure modes, and fiscal implications), the description covers the essential behavior, edge cases, and points to full documentation. It lacks an explicit return-value specification, but for a delete operation this is often unnecessary. It's sufficiently complete for correct invocation.
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 coverage is 100%: both company_id and series_id have full descriptions. The description does not add parameter-specific details beyond what the schema already provides, so it stays at baseline. No additional semantics are offered.
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 'Soft-deletes an invoice series', a specific verb and resource, and clarifies it deactivates first if active. This distinguishes it from sibling tools like beel_patch_series (modify) or beel_deactivate_by_id (deactivate) by focusing on deletion. It also explains the soft-delete consequence (code stays taken), further clarifying the operation's scope.
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?
Provides concrete conditions for when deletion is allowed: a default series cannot be deleted while another active series of the same type exists, and if it's the only series, deletion leaves the type without a default. It also gives consequences (e.g., SERIES_DEFAULT_NOT_FOUND on subsequent issues). However, it does not explicitly name alternative tools or state 'use this instead of X', though the conditions imply when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation readOnlyHint:true already declares the read-only nature. The description adds the specific return content (titles and URLs), which is useful beyond the annotation. No contradictions.
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 a single sentence, front-loaded with the action, with no superfluous details. Efficient and clear.
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?
For a simple list tool with no parameters and an output described, the description covers what an agent needs: it returns titles and URLs. Annotations cover read-only safety. No output schema exists, but the description hints at what the response contains. Given its relative simplicity, the description is complete.
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?
The tool has no parameters, so the baseline is 4. The description correctly does not need to elaborate on parameters.
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: lists documentation pages, specifying that it returns titles and URLs. This distinguishes it from sibling tools like beel_docs_search and beel_docs_get, which handle searching or retrieving specific pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the purpose (obtain an overview of available docs) but does not explicitly mention alternative tools or when not to use it. Given the existence of beel_docs_search and beel_docs_get, additional guidance would be helpful, but the intent is reasonably clear from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds critical behavior beyond those: the 404 response when no schedule exists, the need to capture generation_mode for the subsequent PUT, and fiscal guardrails warning about AEAT misreporting. This is substantial operational context not present in structured metadata.
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?
The description is well-structured: purpose first, then 404 behavior, then the PUT hint, endpoint, and fiscal guardrails. It is longer than minimal but each section adds value. The guardrail bullet points are somewhat vague and could be condensed, but the overall organization is effective and front-loaded.
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?
For a two-parameter GET with no output schema, the description covers the return type, a key edge case (404), the relationship to a PUT operation, and points to docs for full details. The annotations cover safety, so the description is reasonably complete. It stops short of describing the exact return format, but the docs pointer and annotations suffice.
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% — both parameters are documented. The company_id description even explains its role as the sole context source and the 403 error behavior. The description itself adds no parameter-specific semantics beyond what the schema already provides, so the baseline of 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 description states exactly what the tool returns: the scheduled date and generation mode for a given invoice. It also clarifies the 404 edge case for unscheduled invoices, which distinguishes this from tools like beel_set_invoice_schedule or beel_delete_invoice_schedule. The purpose is specific and unambiguous.
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?
The description gives concrete usage guidance: read the current generation_mode here before a PUT to move only the date, and it directs agents to beel_docs_search for exhaustive rules. While it does not explicitly list alternative tools or say 'don't use this for X', the PUT interaction and the pointer to docs make the intended context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, and the description redundantly says 'Read-only' – that is consistent. Crucially, it adds behavioral detail beyond annotations: it discloses that it aggregates several endpoints and 'degrades gracefully on partial failures', which tells the agent that isolated failures won't abort the whole call. This is useful context the agent could not have guessed from annotations alone.
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 three tight sentences, each earning its place: purpose and scope, what it reports, and why to use it. It front-loads the read-only nature and aggregates status, and ends with a practical directive. Zero filler.
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?
For a single-parameter read-only report tool with an output schema, this description is complete. It explains the report's content, the aggregation behavior, graceful degradation, and the recommended next action. The presence of an output schema means return-value details need not be in the description. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter company_id is already fully described in the schema ('Optional: restrict the report to a single company (NIF) id.'). The description reiterates the per-NIF behavior and the optional restriction, but adds no new syntax or format details beyond the schema. Schema coverage is 100%, so a baseline 3 is appropriate; the description adds marginal value here.
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 states a specific verb and resource ('Read-only setup status across your account'), explains the granularity ('for each NIF (company)'), and details exactly what it reports (blockers, default series, VeriFactu, payment connection, recommended next action). It clearly differentiates from siblings by noting it 'aggregates several endpoints' and targets onboarding rather than a single inspection.
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 explicitly says 'Use this to drive onboarding instead of guessing', giving a clear when-to-use scenario. It does not name specific alternative tools or exclusions, but the scope ('across your account' and optional single-company filter) implies when a more targeted call might be preferred. It lacks explicit 'when not to use' guidance but is still very actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds value beyond annotations by explaining that events belong to the connection rather than the NIF directly, that only that connection's events are returned, and that a missing connection yields 404. It also states the 'most recent first' ordering. These are behavioral details not in the annotations, though some like pagination are left to the schema.
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 compact and well-structured: a first sentence stating purpose and ordering, a bolded scoping clarification, a direct statement of the 404 case, and the endpoint. Every sentence earns its place, and the most actionable information is front-loaded. No fluff.
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?
For a list operation with only 4 parameters, full schema coverage, and annotations covering safety (read-only, idempotent), the description is complete. It explains the ownership/management condition, the connection-scoping rule, the 404 error, and the ordering. The endpoint is provided. Nothing an agent needs to call it correctly is missing; output schema is not required for a list operation.
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 coverage is 100%, so all parameters (company_id, provider, page, limit) have detailed descriptions in the input schema. The description does not add much new parameter-level meaning; it repeats that provider selects the connection and that company_id is the sole context source, which are already in the schema. With full schema coverage, the baseline of 3 is appropriate; the description adds marginal semantic value.
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 uses a specific verb ('Lists') and names the resource precisely: 'payment events received through the payment provider connection of a NIF (company) that your account owns or manages, most recent first.' It clearly distinguishes from single-event retrieval by the plural 'events' and the explicit use case of auditing charges. The scope is unambiguous, and the phrasing differentiates it from other list operations in the 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?
The description gives a clear intended use case ('Use it to audit the charges that produced an invoice and to find the ones that did not') and scopes the operation to connections of owned/managed NIFs. It does not explicitly name alternatives like beel_get_payment_event for single-event lookup, but the plural and audit purpose make the distinction clear. The explicit 404 case also adds contextual usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state not read-only and idempotent. The description adds that COMPLETED cannot be set and explains rejected transitions. It also warns about fiscal guardrails, which is important. No contradiction. It adds value beyond annotations.
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?
The description is structured with bullets and warnings. It is somewhat long but front-loaded with the main purpose. The fiscal guardrail warning is useful but could be trimmed. Overall, it's well-organized.
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?
The description covers statuses, rejected transitions, fiscal guardrails, and points to docs for exhaustive rules. No output schema is present, but the description doesn't need to explain return values. It provides enough context for an agent to call correctly.
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 low (33%), but the description adds semantic meaning for 'status' (explains ACTIVE and PAUSED) and for 'company_id' (explains NIF usage and 403 behavior). The 'recurring_invoice_id' is left to the schema but it's a UUID. The description compensates for the low coverage.
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 uses a specific verb 'Sets' and resource 'recurring invoice template', and clearly explains the two statuses PAUSED and ACTIVE. It distinguishes COMPLETED as not settable. This clearly communicates the tool's purpose and differentiates from related invoice status tools.
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?
The description explains that this is for pausing and resuming generation, but it does not explicitly mention alternative tools or when not to use it. However, the context is clear from the tool name and the explanation. It mentions rejected transitions, which gives usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds meaningful behavior: partial updates (only properties present are modified), effect only on future invoices (not already issued documents), and logo managed through a sub-resource. This gives the agent a clear picture of side effects and scope without contradicting any annotation.
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 concise—three sentences that front-load the core action and scope, mention partial-update semantics, note the logo sub-resource, and state the endpoint. No redundant or filler content; every sentence contributes to understanding.
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?
For a partial-update tool with no output schema, the description covers all essential aspects: the resource, the fields, the partial behavior, the logo handling, and the future-only effect. An agent can invoke this correctly without additional info about prerequisites or responses.
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?
The input schema already describes company_id and the body properties with formats, examples, and patterns; however, schema description coverage is only 50% at the top level (body lacks a direct description). The description reiterates which fields can be updated but doesn't add parameter-specific syntax or constraints beyond the schema. It does clarify that the update is partial, which is useful context.
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 clearly states the verb ('updates') and the resource ('how the invoices of a company are rendered and delivered'), and enumerates specific aspects it modifies (PDF template, accent colour, invoice language, email language). It also clarifies partial-update behavior and that the logo is handled via a sub-resource, which distinguishes it from get/list tools such as beel_get_invoice_customization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context on how updates behave (only provided properties modified, logo via sub-resource) but does not explicitly name alternatives or state when to use this tool versus others. For example, it doesn't mention that reading current settings should use beel_get_invoice_customization, or that logo updates are done through a separate endpoint. The guidance is inferred rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond the annotations: the token is returned once and never readable again, so it must be delivered to the invitee. It also explains that email is not sent by default and that send_email triggers an email. These details add value beyond readOnlyHint=false and destructiveHint=false. It does not mention idempotency behavior or rate limits, but the schema covers idempotency_key, and the core behavioral constraints are well exposed.
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?
The description is thorough yet well-organized. It front-loads the core purpose and token delivery warning, then addresses grants and role restrictions, and finally covers email behavior. The endpoint is appended as a minor redundancy since the schema already indicates the HTTP method. Overall, it is efficient and each sentence contributes useful information without excessive padding.
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?
For a tool with a nested body, role enum, and grants array, the description covers the essential aspects: single-use token, grants rules, role restrictions, and email default. It does not repeat schema details like idempotency_key or specific error codes (which are in the schema), but it provides enough context for an agent to correctly invoke the tool. The description is complete for typical usage, though it could mention the idempotency_key option more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description substantially enhances parameter understanding. It explicitly states that grants is required and explains its usage for MEMBER (including [] for no access), clarifies that grants are only valid for MEMBER because OWNER and ADMIN have implicit access, and notes that OWNER cannot be invited. It also explains the effect of send_email. These clarifications go beyond the already-rich schema descriptions, making the parameter semantics much clearer and more actionable.
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 explicitly states the verb ('creates') and resource ('single-use invitation'), and specifies the return value (acceptance token). It clearly distinguishes this tool from siblings by emphasizing the single-use nature and the account-join context. No other sibling tool creates invitations, so the purpose is unambiguous.
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?
The description provides clear context on when to use this tool: to invite a person to join the account. It gives important usage guidance such as OWNER cannot be invited, grants are only for MEMBER, and the default email behavior. However, it does not explicitly name alternative tools (e.g., beel_list_invitations, beel_delete_invitation) or state a 'when not to use' condition, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the concrete consequence 'No further events are delivered to its URL' and the reversible alternative, which go beyond the annotations by explaining the impact and providing a decision path. While the 'permanently deletes' phrasing partially mirrors the destructive hint, the added context about stopping delivery and the alternative justifies a score above the baseline.
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?
Two sentences plus an endpoint line, zero filler. The primary action is front-loaded, the consequence is stated, and the alternative is provided in the second sentence. Every sentence earns its place, and the structure is immediately scannable.
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?
The tool has only 2 parameters, both fully documented in the schema, and annotations cover destructiveness and idempotency. The description supplies the key usage decision (permanent vs reversible) and the endpoint. No output schema exists, so return values are undefined, but for a destructive delete that's acceptable. Slight gap: no mention of what the response contains (e.g., success/failure body), but this is minor given the annotations and simplicity. Complete enough for an agent to call correctly.
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?
The input schema descriptions are exceptionally detailed, covering 100% of parameters, including nuanced authorization and error-disclosure semantics (403 for unauthorized accounts, 404 for non-existent subscriptions). The description itself adds nothing about parameters, but the schema fully covers them. Per the rubric, baseline is 3 when schema coverage is high, and no additional param info is needed.
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 clearly states the verb and resource: 'Permanently deletes a webhook subscription.' It distinguishes this from the related sibling tools beel_create_webhook_subscription and beel_patch_webhook_subscription by emphasizing permanence, which is not present in the other tools' names. The addition of the endpoint clarifies the exact operation, leaving no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use this tool: when a permanent deletion is desired. It also directs the agent to the reversible alternative, `beel_patch_webhook_subscription`, by stating 'To stop deliveries reversibly, set `active` to `false` instead.' This is a clear when/alternative directive that maps directly to a sibling tool, satisfying the dimension fully.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already mark this destructive, the description goes far beyond them: it discloses credential deletion, immediate auto-invoicing halt, ignored incoming charges, unaffected already-issued invoices, and the persistence of provider-side authorization. This is exemplary behavioral disclosure for a mutation tool.
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?
The description is well-structured and front-loaded with the most important action and side effects. It is slightly longer than strictly necessary due to the endpoint line and the detailed provider-dashboard caveat, but every sentence contributes meaningful operational context.
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?
For a destructive operation with no output schema, the description covers all essential context: eligibility, immediate effects, unaffected invoices, provider-side authorization requirements, and error/privacy behavior via the company_id schema. Nothing critical is missing for an agent to invoke this tool correctly and safely.
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 schema descriptions are already rich, covering the provider enum, lowercase requirement, company context derivation, and 403 privacy semantics. The main description adds little parameter-specific meaning beyond restating 'stripe' and 'NIF', so the baseline of 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 description states a specific action (disconnect), a precise target (payment provider connection of a NIF the account owns or manages), and the provider (Stripe). It clearly distinguishes itself from related tools like beel_list_payment_connections or beel_initiate_payment_connection by describing its destructive effect.
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?
The description gives clear eligibility context (company must be owned or managed), explains what happens when used, and explicitly notes that provider-side authorization is not revoked, pointing the user to the provider dashboard for that. It does not name sibling alternatives such as the initiate/list payment connection tools, but the usage context is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond annotations: creation codes (F, S, R), format {CODIGO}-{YYYY}-{NUM:4}, omitting types if code taken, and the fiscal guardrail warning. These details are not in annotations, which only declare idempotent and non-destructive.
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?
Structured with a clear opening sentence, then idempotency, behavior, endpoint, and guardrails. Each section adds necessary details; slightly long but justified for the fiscal complexity. The fiscal guardrail and docs pointer are front-loaded after the core purpose.
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?
Comprehensive for its complexity: explains the expected end state, edge cases (code conflicts), the endpoint, and fiscal guardrails. It also points to beel_docs_search for exhaustive rules, covering the absence of an output schema by describing what is returned.
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 schema already thoroughly explains company_id including auth and non-disclosure. The description adds no meaning to the parameter itself, only mentions the request has no body, which is not parameter-specific.
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?
Clearly states the tool ensures the company has a default invoice series for STANDARD, SIMPLIFIED, and CORRECTIVE, and returns the resulting set. The verb 'ensures' and specific resource distinguish it from sibling tools like beel_set_default_series or beel_get_default_series.
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?
Implies usage by stating the request takes no body and repeats change nothing, indicating it is idempotent and can be called to guarantee defaults. It references fiscal guardrails and points to beel_docs_search for exhaustive rules, but does not explicitly contrast with setting a specific series via beel_set_default_series.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description goes beyond by detailing what is NOT done (not issued, numbered, emailed) and the draft state. It also discloses security behavior (403 for inaccessible NIFs) and error responses, adding valuable context beyond the annotations.
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?
Three concise paragraphs, each with a clear purpose: functionality, error conditions, and endpoint. No fluff, front-loaded with the primary action, and every sentence contributes to understanding.
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?
For a creation tool with no output schema, it covers the essential operational context: preconditions, error cases, and the manual follow-up action. It could mention retrieval or further steps beyond issuing, but the description is sufficiently complete for correct invocation.
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 parameter descriptions are extremely detailed (e.g., provider enum, company_id NIF behavior, idempotency_key semantics). The tool description itself adds no parameter meaning, so the baseline of 3 is appropriate; the schema carries the full burden.
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 states a specific action ('Builds a draft invoice') with the exact resource (payment event) and context (could not be invoiced automatically). It clearly distinguishes itself from the automatic flow and siblings like beel_retry_payment_event or beel_get_payment_event by specifying it produces a draft, not an issued invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly defines when to use: only for events that produced no invoice. It also provides the 400/422 error conditions as guardrails, and instructs the agent to issue the draft manually. This gives clear usage context and excludes misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: period default, max range, error response format (400 with reason in details.reason), and the inclusion of annual projection and bracket breakdown in the output. It also mentions the endpoint. It does not fully describe output structure or potential edge cases, but it goes beyond annotations meaningfully.
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?
Two concise sentences. The first describes the output, the second details constraints and error behavior. No redundant information, fully front-loaded, every sentence earns its place.
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?
Given the read-only nature (annotations cover safety), the schema covers parameters, and the description covers output contents and error handling, the definition is quite complete. It lacks an explicit output schema but provides a high-level summary of what is returned. It could mention whether authentication or permissions are needed, but that is likely covered by the endpoint context. Overall, adequate for an agent to call correctly.
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 each parameter is already documented. The description adds additional semantic value: the period defaults to the current month, ranges over 365 days are rejected, and inverted ranges trigger a 400. These are constraints not present in the schema, so the description enhances parameter understanding.
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 states exactly what the tool returns: 'Returns the VAT and IRPF summary of the invoices issued under this company (NIF) over the requested period, together with the annual IRPF projection and its progressive bracket breakdown.' This is a specific verb+resource, and it clearly distinguishes from any sibling by naming the fiscal summary concept. No ambiguity.
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?
The description provides clear context: the period defaults to the current month, cannot exceed 365 days, and invalid ranges return a 400 with reason in details.reason. It also notes the endpoint. It does not explicitly name alternatives, but given the unique purpose and the large sibling list, the usage context is sufficiently clear. It could improve by stating 'use this when you need fiscal summary data' but it's adequately implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes well beyond that: it defines the semantics of `ready` and `blockers`, explains the VeriFactu chain conditions, clarifies that readiness is per-NIF and independent per company, and even details behavior when `verifactu_enabled` is explicit. This adds substantial behavioral context that an agent cannot infer from annotations alone. No contradictions found.
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 structured in clear paragraphs with the primary purpose front-loaded. Every sentence earns its place: the VeriFactu explanation is critical, the explicit exclusions prevent false expectations, and the guardrails pointer is a useful reference. The length is justified by the complexity of the tool without redundancy.
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?
Given the tool's complexity and the absence of an output schema, the description provides a reasonable outline of the response semantics (ready, blockers, verifactu block) and points to beel_docs_search for full details. It lacks an exhaustive enumeration of possible blockers or the exact response shape, but the pointer to docs compensates. For a read-only check with annotations covering safety, this is sufficiently complete.
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?
The single parameter `company_id` is already fully documented in the input schema (100% coverage), including its semantics as a NIF, its role as the sole source of context, and the 403 response behavior. The tool description adds no further parameter-specific information. Per the calibration guidelines, baseline 3 is appropriate when schema coverage is high.
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: 'Returns whether a company (NIF) can issue its STANDARD invoice right now' — clearly stating the action and the subject. It distinguishes this from other fiscal tools by focusing on readiness and blockers, and it clarifies the per-NIF scope. This is unambiguous and unique among the many sibling tools.
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?
The description explains when this tool is relevant (pre-check before issuing a standard invoice) and explicitly disclaims what it does not evaluate (quota, subscription, payload), which prevents misuse. It points to docs for exhaustive rules and includes a fiscal guardrails pointer. It does not explicitly name an alternative tool like beel_issue_invoice, but the context strongly implies readiness is a precursor. This is clear enough for an agent to decide when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavior: the return of a NOT_STARTED state with HTTP 200, and the safety for polling. Additionally, the parameter description within the schema (which is part of the input schema) reveals authentication behavior: a NIF not reachable returns 403, and nonexistent NIFs also return 403 to avoid disclosing existence. This goes well beyond what annotations convey and is a substantial contribution to transparency.
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 concise and well-structured. It starts with the purpose, then explains the important non-error behavior, and ends with the endpoint. Every sentence adds value, and there is no redundancy with the annotations or schema. It is front-loaded with the main purpose, and the endpoint line is a helpful technical detail.
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?
Given there is no output schema, the description provides an adequate overview of the return states and the safe polling behavior. It does not detail the exact JSON response structure, but the states listed (NOT_STARTED, generated, signed, submitted, accepted, cancelled) give the agent enough to interpret results. The tool has a single parameter with thorough documentation, and its read-only/idempotent nature is declared. The description is complete for practical usage, though a mention of the response fields would make it slightly better.
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 company_id parameter description is already very rich: it explains the NIF is the only context, the account is derived from it, the header is ignored, and 403 behavior for unreachable/nonexistent NIFs. The tool description itself adds no additional parameter semantics beyond what the schema provides. Since the schema covers everything, a baseline score of 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 description clearly states the tool's purpose: it returns the state of AEAT fiscal representation for a company (NIF), enumerating the specific states (generated, signed, submitted, accepted, cancelled). The verb 'returns the state' is specific and the resource is the representation. It implicitly distinguishes itself from sibling tools like generate_representation and download_representation_document by focusing on the state query.
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?
The description provides clear usage guidance by stating that a company that never started the process is not an error and that polling is always safe. This tells the agent when it is appropriate to call the tool repeatedly. However, it does not explicitly name alternative actions like generate or download when the state indicates a certain stage, leaving some inference for the agent. It gives context but not explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations, detailing the asynchronous authorization flow, the fact that the connection is created only after holder authorization, the activation requirement with specific error code, and the callback redirect behavior with error codes. It clarifies side effects (idempotency, non-appearance until authorization) and environmental handling (test/live), which annotations only hint at via flags.
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?
The description is longer than typical but every sentence carries useful information, covering purpose, flow, activation, and return details. It is well-structured with clear paragraphs, front-loading the core action before diving into conditions. While not terse, it is appropriately detailed for the complexity of the operation.
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?
For a tool with no output schema, the description fully covers what an agent needs: the authorization flow, the returned authorization_url, the dependent parameters (return_url with appended statuses), the activation prerequisite with error handling, and idempotency nuances. It leaves no critical gaps for correct invocation.
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 coverage is 67% and provides descriptions for company_id, body (provider and return_url), and idempotency_key. The description adds behavioral context about activation and error conditions but does not significantly enhance parameter semantics beyond what the schema already offers. It reiterates provider constraints but mainly repeats schema details, so it meets baseline without adding substantial new parameter-level meaning.
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 clearly states the tool's purpose: it opens an authorization session for a NIF holder to connect a payment provider and returns an authorization_url. It specifies the verb ('Opens an authorization session'), the resource (payment connection), and the action (returns the URL), and it distinguishes itself from related tools like beel_disconnect_payment_connection by focusing solely on initiation.
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?
The description provides clear context on when to use this tool: when you need to connect a payment provider for a managed NIF. It explains the prerequisite (NIF activation) and the flow, and it implies the alternative (disconnect) is different, but it does not explicitly state 'when not to use' or name an alternative tool. Since no direct alternative exists among siblings, it's acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the key behavioral fact that only documents of the company in the path are returned, and scopes the account context (company_id is the only source of context; header plays no part). It also warns about fiscal guardrails (when an invoice can still be changed) and directs to docs for exhaustive rules. This adds value beyond the annotations, though it doesn't mention pagination details or rate limits explicitly, but the baseline is lowered by strong annotations. No contradiction found.
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 short, front-loaded with the core purpose, then the endpoint, then a pointed warning about fiscal guardrails and a pointer to docs. Every sentence earns its place; the guardrail note is specifically actionable. No redundancy with annotations. Structure is clear and concise.
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?
For a complex 25-parameter list tool with no output schema, the description gives the essential context: scope, key filters, and a critical safety pointer (guardrails). It does not enumerate every filter but the schema already does that (100% coverage). The description handles the company scoping nuance and directs to docs for exhaustive rules, which is appropriate given the tool complexity. Missing pagination specifics (like default limit, max) are minor and covered by schema defaults. It is sufficiently complete for an agent to call correctly.
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 description coverage is 100%, so according to the rubric, the baseline is 3. However, the description adds value by summarizing the key filter categories (status, type, series, customer, date range, free text) which helps the agent see the breadth without reading every parameter. It also mentions 'free text' which maps to the `search` parameter and highlights the `fiscal_only` concept implicitly via 'invoices of this company'. The description does not repeat parameter details—that's left to the schema—but it provides a useful high-level summary. Since coverage is high, and the description adds a compact view of the filters, a 4 is justified.
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 states a specific verb ('Returns'), resource ('paginated list of invoices'), scope ('this company (NIF)'), and lists filterable dimensions (status, type, series, customer, date range, free text). It also explicitly scopes results to only the company in the path, clearly distinguishing it from any global list. The endpoint is named, and the guardrail reference adds context. This clearly separates it from siblings like beel_list_invitations and other list tools.
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?
The description clearly states when to use: to list invoices of a specific company, with extensive filtering options. It does not explicitly mention when not to use alternatives, but the scoping to a single company and the guardrail note about invoice state machine provide context. The mention of 'fiscal guardrails' and reference to beel_docs_search for exhaustive rules gives usage direction, though there are no explicit exclusion criteria against other list tools. This is better than many because it points to a docs search for edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent hints already in annotations, the description adds rich behavioral detail: pagination response modes (data.series vs data.pagination), the unconditional inclusion of UNASSIGNED series, and the company_id auth behavior (403 for unreachable/non-existent NIFs, no existence disclosure). This goes well beyond the annotations.
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?
The description is well-structured: core purpose first, then pagination behavior, endpoint, and safety warnings. Each sentence adds value given the fiscal complexity, though it is longer than strictly minimal. The front-loading of the purpose and the logical flow justify the length.
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?
Despite lacking an output schema, the description discloses response shape (data.series vs data.pagination with totals), pagination modes, auth context, and points to further docs. It leaves no critical ambiguity for an agent to call the tool correctly.
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?
The input schema already provides complete descriptions for all 5 parameters (100% coverage), including pagination semantics, company_id context, and the UNASSIGNED filter behavior. The description largely reiterates these points without adding new parameter-level meaning, so it meets the baseline for high schema coverage.
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 clearly states a specific verb and resource: 'Returns the invoice series of a company (NIF)', with optional filters named ('active', 'document_type'). It includes the endpoint and even notes the UNASSIGNED inclusion, making it unambiguous and distinct from list operations on other resources.
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?
The description gives practical usage context: explains opt-in pagination (sending page/limit vs omitting), notes that document_type always includes UNASSIGNED, and points to beel_docs_search for exhaustive rules. It does not explicitly name alternative tools like beel_get_series, but the purpose is specific enough that an agent can select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false (mutation), destructiveHint=false (non-destructive), and idempotentHint=true. The description adds valuable behavioral context beyond annotations: it specifies that only the company in the path is touched and other grants remain unchanged, and it warns that NONE is not accepted. It also clarifies the implicit access of OWNER/ADMIN roles. This provides a clear behavioral profile without contradicting annotations.
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 compact and information-dense, starting with the core purpose, then scope, then edge cases, and ending with the endpoint. Every sentence contributes unique information without redundancy. It is front-loaded with the most critical facts and avoids any filler, making it efficient for an agent to parse quickly.
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?
For a mutation tool with no output schema, the description covers the essential aspects: the action, the scope of mutation, the non-accepted value, and the special case of OWNER/ADMIN. It also provides the endpoint and path parameter composition. It does not mention authentication requirements or error responses for invalid members, but these are largely implied by the schema descriptions (e.g., account_id mentions 403). Overall, the description is sufficiently complete for an agent to call the tool correctly.
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 high (75%), and the schema already documents each parameter with descriptions, including the body's access_level enum and the note that the company is taken from the path. The description does not add new parameter-level meaning beyond what the schema provides; it mainly reiterates the exclusion of NONE and the path-dependence. Since the schema carries the semantic load, a baseline of 3 is appropriate, and the description adds minimal extra value.
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 states a specific verb-resource pair: 'Grants a MEMBER access to one company, or changes the access_level of an existing grant.' It clearly identifies the resource (member's grant for a company) and explicitly differentiates from siblings like beel_delete_member_grant by noting that NONE is not accepted and removal is done via deletion. It also clarifies that only the company in the path is affected, distinguishing it from broader grant management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: use it to grant or change access, and explicitly says to remove access by 'deleting the grant' (pointing to a sibling tool). It also states that OWNER and ADMIN members cannot receive grants, which prevents incorrect calls. These exclusions and alternatives are clearly stated, leaving no ambiguity about when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint=false and destructiveHint=true, but the description goes far beyond: it specifies that TOTAL voids the original, PARTIAL leaves it RECTIFIED, describes series default creation behavior and the resulting 422 error codes, and warns about misreporting to AEAT with guardrail resources. This adds contextual side-effect information the annotations do not convey.
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?
The description is long but every section serves a purpose: purpose, behavioral consequences, status rules, series semantics, endpoint, and guardrails. It is front-loaded with the core purpose and structured in clear paragraphs. The length is justified by the complexity, though it could be slightly trimmed without losing value.
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?
For a complex tool with no output schema, the description covers the core usage, status conditions, error scenarios, series handling, and points to guardrails and docs_search for exhaustive rules. It omits some details like idempotency_key behavior, but that is fully specified in the schema. Overall it provides enough for an agent to invoke the tool correctly without external research.
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 75% and the schema itself thoroughly documents parameters like series_id, lines, and rectification_type. The description repeats some of these points (e.g., series default, line copying) but adds little new meaning beyond behavioral context like error codes. Since the schema carries the heavy lifting, the description adds marginal value here, hence a baseline 3.
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 states a clear verb and resource: 'Issues a corrective invoice that amends the invoice in the path.' It also explicitly distinguishes itself from editing ('It is a new fiscal document with its own number, not an edit of the original') and implies differentiation from void/patch tools. This leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It enumerates exactly which invoice statuses are rectifiable (ISSUED, SENT, PAID, OVERDUE, RECTIFIED), what to do when a corrective itself is faulty ('issue another one against the original invoice'), and when a TOTAL cannot be repeated (VOIDED invoice). It also clarifies series default behavior and points to guardrails for the cancel-vs-rectify decision, giving agents clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal annotations (readOnlyHint false, destructiveHint false), the description discloses important behavioral details: the source invoice is not modified, specific fields are reset, and series validation may fail with a specific error (422 SERIES_INCOMPATIBLE_DOC_TYPE). It also highlights fiscal guardrails and points to documentation for edge cases. This is rich behavioral context that goes well beyond what annotations provide.
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?
The description is longer than typical but well-structured: a clear opening sentence states the purpose, followed by copy/reset details, a note on series validation, the endpoint, a guardrail warning, and a pointer to docs. Each section earns its place, though some redundancy exists (e.g., repeating the mode and source behavior). It is effectively front-loaded and easy to scan, but could be slightly tightened.
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?
Given the complexity of the operation, the absence of an output schema, and the detailed input schema, the description covers essential aspects: what gets copied and reset, the source not being modified, series validation and error handling, and where to find exhaustive rules. It does not explicitly state the return value, but that is consistent with the lack of an output schema and is not required for correct invocation. The references to docs and guardrails fill remaining gaps, making it sufficiently complete.
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?
With schema description coverage at 67% (two of three parameters documented in detail), the description compensates by explaining the conceptual role of parameters: from_invoice_id names the source, mode DUPLICATE copies it, and series_id defaults to the source's. It clarifies the intent that this call does not describe an invoice but names one, which adds meaning beyond the schema's property descriptions. However, it does not dwell on idempotency_key semantics, which are already present in the schema, so the added value is strong but not exhaustive.
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 states a specific verb and resource: 'Creates a draft invoice derived from an existing invoice'. It details exactly what is copied and reset (recipient, lines, payment method, series, observations, number, status, dates, VeriFactu data, PDF) and distinguishes itself from beel_create_invoice by explaining this call names a source invoice rather than describing one, and from beel_convert_proforma_to_invoice by noting it is not a derivation mode. This makes the purpose unambiguous and clearly separates it from siblings.
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?
The description provides clear context for when to use this tool: it is for duplicating an existing invoice, explicitly contrasting with the standard create request ('not a variant of the create request on purpose') and mentioning that turning a proforma into an invoice is a different operation. It also advises consulting fiscal guardrails and points to beel_docs_search for exhaustive rules. However, it does not explicitly enumerate all sibling alternatives in a structured when/when-not form, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral context by specifying it fetches the 'full' page with 'all its sections', which is not in the annotations. It does not disclose potential failure modes, but for a read-only docs fetcher this is sufficient.
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 a single, focused sentence stating the core action and scope, followed by a practical usage tip. No wasted words, and the key information is front-loaded.
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?
For a simple tool with one parameter, no output schema, and read-only annotations, the description covers the essential aspects: what it does, when to use it, and how to pass the parameter (via the schema). The behavior of returning a full page is clear, and no critical details are missing for an agent to call it correctly.
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 coverage is 100%, with the parameter described as 'Page title or a distinctive part of it.' The description adds only illustrative examples ('Invoice types', 'Regime keys') that mirror the schema. Since the schema already defines the semantics, the description provides marginal value, warranting the baseline score of 3.
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 states a specific verb ('fetch') and resource ('full documentation page by title'), and clarifies it returns all sections. It also gives concrete examples ('Invoice types', 'Regime keys') and explicitly situates itself after beel_docs_list or beel_docs_search, distinguishing it from those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use this tool: 'Use after beel_docs_list or beel_docs_search to read a page in full.' This clearly indicates the workflow — list/search to find a page, then this tool to get its full content. No exclusions are needed given the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds useful behavioral context beyond these: it explains the catalogue is not nested under an account, returns translated labels, and that its output feeds the template_type field of a PUT operation. This adds clarity without contradicting annotations.
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 two focused paragraphs plus the endpoint, front-loading the core purpose and value-add. Every sentence serves a purpose: the first introduces the output and its fields, the second clarifies the value over the enum and the global scope, and the endpoint is appended for reference. No wasted words.
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?
For a zero-parameter, read-only list operation with no output schema, the description covers everything an agent needs: what is returned (templates with code, name, description), how the code is used in a related endpoint, and the global nature of the catalogue. It does not omit any critical detail for correct invocation.
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?
There are zero parameters, so the description correctly avoids parameter-specific guidance, meeting the baseline of 4 for no params. It still explains the relationship between the output (code) and the parameter template_type, which is semantically helpful.
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 states a specific verb ('Returns') and a clear resource ('PDF templates a NIF can be rendered with'), and explains the exact value-add: providing readable labels for template_type enum values. It distinguishes itself from customization-related tools by clarifying it lists options rather than applying or reading a specific customization, making it immediately identifiable among siblings.
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?
The description implies usage context: when you need to display human-readable template type labels instead of enum codes, and notes the catalogue is global ('identical for every account and every NIF'), so it is not scoped to a specific account. However, it does not explicitly name alternative tools or state when NOT to use it, so it falls short of full explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds crucial behavioral detail beyond those: it clarifies that null clears a field (distinct from omission), that untouched fields are preserved, and that the resulting product goes through the same validation as PUT. This is significant context not derivable from the annotations or schema alone. No contradiction with annotations.
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?
The description is longer than typical but every sentence contributes: partial-update semantics, null handling, contrast with PUT, and endpoint. It is front-loaded with the core rule and efficiently organizes the rest. While it could be tightened, there is no fluff; it earns its length.
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?
The tool handles a complex request body (PatchProductRequest) with nested tax rules, and the description covers the essential behavioral contract: partial update, null clearing, validation equivalence, and the preserved fields. There is no output schema, so a note on return value is absent, but that is a minor gap given the richness. It is complete enough for an agent to call correctly.
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?
The schema already provides thorough descriptions for company_id, product_id, and the nested PatchProductRequest fields. Schema description coverage is 67%, and the description itself does not add parameter-specific meaning beyond what the schema documents. It mentions the endpoint path, which implicitly maps parameters, but adds no new semantic insight. Baseline of 3 is appropriate given the schema coverage.
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 the precise effect: 'Updates only the fields present in the body, leaving every other field of the product as it is', naming specific fields that are preserved. It clearly identifies this as a partial update (PATCH) and contrasts it with the full-replacement PUT. The endpoint is given explicitly, and the presence of sibling patch tools (e.g., beel_patch_customer, beel_patch_invoice) makes the distinction unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with the alternative PUT verb: 'the total replacement PUT /v1/products/{product_id}, which reset the omitted fields to their creation defaults, is not carried over.' It also explains the null-vs-omit semantics, which is essential for correct usage. This is direct guidance on when to use this tool and what it does not do.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency and non-destructiveness, but the description adds substantial behavioral detail: `events` replaces the entire list (not additive), the signing secret is untouched, and `active=false` stops deliveries without discarding history. No contradictions with annotations.
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?
Three concise paragraphs, each carrying distinct information: the partial-update behavior, the replacement semantics, and the secret/active considerations. The endpoint line is somewhat redundant with the tool name, but the overall structure is efficient and front-loaded.
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?
The description covers the non-obvious behaviors crucial for correct use: partial updates, list replacement, secret rotation, and the non-destructive nature of disabling. It omits `account_relationship` from the field list (though schema covers it) and doesn't mention response format, but for a mutation without output schema this is adequate.
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 descriptions are rich (67% coverage) and cover all three parameters, including nested body fields. The description adds one crucial semantic — `events` replaces the whole list — but omits the `account_relationship` field (also updatable) from its enumeration. Since the schema covers most details, a baseline 3 with slight credit 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 description opens with a specific verb (Updates) and resource (webhook subscription), enumerates the exact fields affected (`url`, `events`, `active`), and clarifies partial update semantics. This clearly distinguishes the tool from siblings like create/delete webhook subscriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use this tool (updating fields of an existing subscription) and routes the user to the separate secret-rotation endpoint for that concern. It also details the consequences of setting `active` to `false`, giving concrete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint false, etc.), the description discloses key behaviors: payload includes `test: true` and synthetic data, signature verification, no retries on failure, absence from delivery history, and idempotency caching behavior with the same Idempotency-Key. These are valuable, non-obvious traits an agent needs to know.
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 multi-paragraph but every sentence provides distinct value: purpose, payload characteristics, retry/history behavior, idempotency, and endpoint. It is well-structured and front-loads the purpose. No redundancy.
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?
For a test operation with no output schema, the description covers all necessary aspects: what it does, when to use, key side effects (no retry, no history, idempotency), and the endpoint. An agent has enough to decide when and how to call it correctly.
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%, so the baseline is 3. The main description adds a bit about idempotency_key behavior ('Repeating the call with the same Idempotency-Key returns the cached result'), but the schema already details this. Overall, the description adds minimal extra beyond the schema, so a 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 description explicitly states the action ('sends a synthetic payload'), the target (the subscription's URL), and the mode (immediately, outside the normal delivery queue). This clearly distinguishes it from sibling tools like create/delete/get webhook subscriptions and retry delivery, which have different purposes.
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?
The description gives a clear intended use: 'verify that your endpoint is reachable and handles deliveries correctly before you rely on real events.' It implies this is for testing only, but does not explicitly name alternative tools or conditions for not using it. The context makes it obvious, but explicit alternatives would push to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint: true), the description adds critical behavioral details: the document is kept, numbers are never reused, VeriFactu cancellation submission, proforma handling with no fiscal effect, and the deprecated/ignored void_date. It also explains idempotency key behavior. No contradiction with annotations; it enriches them substantially.
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?
The description is well-structured with a clear lead sentence, a separate paragraph for proforma specifics, an endpoint line, and a 'Fiscal guardrails' section with bullet points. It is a bit long but every part serves a purpose, and it front-loads the core purpose. Minor deduction for slight redundancy (e.g., repeating the documented behavior of void_date).
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?
Given the fiscal and legal complexity, the description covers the essential decision criteria (regular vs. proforma, corrective vs. void), the state-keeping behavior, and idempotency. It appropriately defers exhaustive rules to beel_docs_search and guardrail resources. It does not detail error responses or output, but there is no output schema and errors are mentioned implicitly. A complete, nuanced description for a delicate operation.
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 75%, and the schema already documents each parameter well (reason, void_date, company_id, idempotency_key). The description adds minimal extra semantics, mostly reiterating the deprecation of void_date and the idempotency key behavior already present in the schema. It does not significantly compensate for the small coverage gap, so the baseline of 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 description clearly states the verb 'voids' and the resource 'issued invoice', and distinguishes itself from corrective invoices by specifying when each applies. It also handles the proforma case, making its purpose unambiguous and separate from sibling tools like beel_create_corrective_invoice or beel_delete_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('when the operation never took place') and when not to ('if it did take place but with errors, issue a corrective invoice instead'). It also explains the proforma scenario and directs the agent to guardrail resources for further decision-making, leaving no room for confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are weak (readOnlyHint=false, openWorldHint=true, no destructive info), so the description carries the full behavioral burden — and it delivers. It discloses the crucial async semantics: a 2xx means 'accepted for submission', never 'registered with AEAT', with submission_status returned as PENDING. It also discloses that proforma is created directly in ACTIVE state, numbered PRO- from the non-fiscal series, and that issue_directly does not apply to it. This goes well beyond the schema, and there is no contradiction with the annotations — the write/issue semantics align with readOnlyHint=false.
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?
The description is long but dense, and nearly every sentence earns its place: core semantics, proforma exception, derivation alternative, endpoint, and the guardrail pointers. It is well front-loaded with the issue_directly and submission_status semantics before the proforma aside. The six-bullet guardrail list is somewhat verbose but each bullet points to a distinct legal constraint, and closing on the beel_docs_search referral is a sensible compression strategy. Slightly long, but appropriately so for the complexity.
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?
For a tool of this magnitude — a nested body schema, no output schema, weak annotations — the description is remarkably complete. It covers the async submission semantics, the proforma special case, the derivation sibling, the endpoint, and surfaces six guardrail resources plus a docs-search fallback for exhaustive rules. Nothing an agent needs to call it correctly is missing; the external resource pointers are the correct way to handle the depth of Spanish fiscal law here.
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 high at 75%, so the schema already documents most parameters in exhaustive detail. The description adds real semantic value on top for the highest-stakes parameters: it explains what issue_directly actually does (numbered and issued in the same call), the verifactu submission_status=PENDING meaning, and how type: PROFORMA behaves. Given the schema does the heavy lifting, the description's targeted clarification of the trickiest fields earns a 4 rather than the baseline 3.
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: 'Creates an invoice under this company (NIF)' with issuer data drawn from the company in the path. It clearly distinguishes itself from siblings by name — it routes copying to beel_create_invoice_derivation, notes CORRECTIVE is handled elsewhere, and lays out proforma issuance behavior. An agent can immediately tell what this tool does and what it is not.
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?
The description gives contextual usage guidance: the issue_directly vs draft distinction, when proforma semantics apply, and an explicit pointer to derivations for copying an existing invoice. However, it does not explicitly contrast against close siblings like beel_create_invoice_batch or beel_create_recurring_invoice, and only implicitly implies CORRECTIVE lives on beel_create_corrective_invoice via the schema rather than the description prose. Clear context with one named alternative, but not a systematic when-to-use/when-not-to-use matrix.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the source invoice is not modified, explains the inheritance behavior of verifactu_enabled, and provides fiscal guardrails. Annotations are sparse (readOnlyHint false, etc.), so the description carries the burden, and it does so well. It does not mention error handling or rate limits, but these are not critical for this tool.
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 well-structured and front-loaded: the core purpose appears in the first sentence, followed by a clear inheritance note, endpoint, and guardrails. It uses bullet points for the guardrails, making it easy to scan. Every sentence adds value without fluff.
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?
For a tool with no output schema, the description provides sufficient context: it defines the operation, side effects (source not modified), key parameter behavior, and points to docs for exhaustive rules. While it does not describe the response format, that is not essential given the absence of an output schema. The inclusion of endpoint and guardrails enhances completeness.
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?
The input schema already provides rich descriptions for parameters like frequency, start_date, from_invoice_id, verifactu_enabled, company_id, and idempotency_key. The description reinforces key semantics (e.g., verifactu_enabled inheritance) and clarifies that only recurrence parameters are needed. With high schema coverage, the description adds context without redundancy.
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 states a specific verb and resource: 'Creates a recurring invoice template of this company taking its lines, recipient, series and payment data from the invoice named in from_invoice_id'. It clearly distinguishes from siblings like beel_create_recurring_invoice by noting it is a derivation that does not require series_id, invoice_type, or lines, making it unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'only the recurrence has to be described', implying when to use this tool (when deriving from an existing invoice). It also contrasts with CreateRecurringInvoiceRequest, stating that alternative requires series_id, invoice_type, and lines, which this call does not carry, providing a clear exclusion. Additionally, it points to guardrails with 'read before calling' resources, giving conditional guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, idempotent, openWorld), the description reveals critical side effects: the customer is retained internally but hidden from the API (404), not returned in any list regardless of the active filter, and its identifier is released for reuse. It also documents the 409 error response for invoice-bound customers and explains that deletion is a one-way operation. This goes well beyond the annotations and helps the agent anticipate consequences.
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?
The description is dense but not bloated. It front-loads the primary action, then explains retention and release, then the error case, and finally the alternative. Each sentence serves a purpose and avoids redundancy. While it could be shortened, the extra detail (e.g., the precise 409 code and the active-filter nuance) is valuable for effective tool selection.
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?
The description fully equips the agent: it covers the precondition (no invoices), post-deletion behavior (404, not listed, identifier released), the conflict case (409), and the recommended alternative (patch active=false). It also states the endpoint, which aids in debugging or manual inspection. No output schema exists, so it need not explain a return value. This is comprehensively complete for a destructive operation.
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?
The input schema already has a descriptive description for company_id (NIF context, 403 handling) and customer_id (UUID). The tool description adds no new parameter-level meaning beyond the schema; it mentions identifier release but does not link it to a specific parameter. With 100% schema coverage, the baseline of 3 is appropriate—the description does not need to repeat schema details.
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 precise verb and resource: 'Deletes a customer of this company (NIF) that has no invoices.' It clearly differentiates from the bulk delete tool (beel_delete_customers_bulk) and the patch tool (beel_patch_customer) by specifying the invoice condition and the alternative for deactivation. The endpoint is also provided, leaving no ambiguity about the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: for customers without invoices. It also gives the exclusion: 'A customer that has invoices cannot be deleted and answers `409`' and prescribes the alternative: 'update it with `active` set to `false` instead of deleting it.' This directly guides the agent to the correct sibling, eliminating guesswork.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations. It clarifies that despite destructiveHint=true, nothing is deleted or anonymised. It explains the exact effect on billing, access, and ownership, and details reversibility conditions. It also states the `manage_accounts` entitlement requirement, which is not present in the schema or annotations. This adds significant behavioral context that an agent needs to use the tool correctly.
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?
The description is ~150 words and divided into three paragraphs, each adding distinct information: primary effect, reversibility, and prerequisite/endpoint. It is front-loaded with the core purpose and rolls out caveats logically. It is detailed but not bloated; every sentence earns its place. A slightly tighter phrasing would be possible, but the structure is effective.
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?
The description covers all essential behavioral aspects for a destructive but nuanced operation: consequences, reversibility, entitlement, and the endpoint. There is no output schema, so return values are not required. The description is complete enough for an agent to know when and how to invoke it, and what to expect. Missing error conditions are minor given the annotations and the detailed narrative.
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?
With 0% schema description coverage, the description must clarify the parameter. It does so by specifying that the account is one 'you provisioned', which contextualizes the account_id as a managed account. This adds meaning beyond the bare schema (a UUID). It doesn't provide format or additional constraints, but the contextual scoping is valuable and partially compensates for the lack of 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 precise verb and object: 'Ends the management relationship over an account you provisioned.' It immediately distinguishes this from other management actions (like changing access level or cancelling representation) by focusing on ending the relationship entirely. It also states concrete consequences (losing access, NIFs no longer billed, holder keeps everything) which makes the tool's intent unmistakable.
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?
The context is clear: this is the tool for ending a management relationship over a provisioned account. It explains when it is reversible (while unclaimed) and that after claiming, it requires consent, but it does not explicitly compare with sibling tools such as beel_change_managed_access_level or beel_cancel_representation. The description implies when to use it, but does not name exclusions or alternatives, so it falls short of a 5 but is clearly above a 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only and open-world, but the description adds specific behavior: it produces an unsigned PDF, only generates (does not sign or submit), rejects incomplete fiscal identity with 400, and rejects existing active representations. This exceeds the annotation coverage and removes ambiguity about side effects and prerequisites.
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?
Three compact paragraphs: the first states the purpose and workflow, the second details failure conditions, the third gives the endpoint. Every sentence carries information; there is no fluff. The purpose is front-loaded, and the structure aids scanning.
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?
The description covers the full workflow and prerequisites, and gives error codes. It does not specify the tool's response format (e.g., whether it returns a status or document ID), but with no output schema and a clear downstream GET endpoint, this is a minor gap. Overall, an agent has enough to call it correctly and know the next steps.
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 coverage is 100% and both parameters (company_id, idempotency_key) already carry rich descriptions in the schema. The tool description itself adds no new parameter meaning beyond what the schema already states — the company_id context is in the schema, and idempotency_key is not mentioned in the tool description. 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 description uses a specific verb ('Generates') plus a precise artifact ('unsigned AEAT representation PDF') and names the target resource ('company (NIF)'). It clearly distinguishes this generation action from sibling tools like cancellation or download, and even spells out the downstream endpoints. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditions for use: fiscal identity must be complete (otherwise 400), and any active representation must be cancelled first. It also frames this tool as the first step of a three-step flow (generate → download → sign/submit), which tells an agent exactly when to invoke it and what to do if it fails. It implicitly contrasts with cancellation and download siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: the billable unit count includes empty and unclaimed accounts, the 404 error for non-own account IDs, and the required `manage_accounts` entitlement. This gives the agent a full picture of what will happen and what is needed, well beyond the annotation hints.
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?
The description is a single cohesive paragraph, front-loaded with the core purpose. It then explains the billable-unit nuance, the ownership requirement, the entitlement, and the endpoint. No wasted words, and each sentence earns its place, though it could be slightly tightened by removing the endpoint line (which is redundant with other metadata). Still, it is well-structured and easy to scan.
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?
For a read-only tool with one parameter and no output schema, the description covers all necessary context: what it returns, the parameter semantics, error behavior, authentication requirement, and even the underlying endpoint. Nothing an agent needs to decide whether to call it and how to call it correctly is missing. The only theoretical gap (response format) is acceptable given no output schema is provided.
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% (account_id described as 'Your own account id.'), so the schema already documents the parameter. The description enriches this by explaining why it must be the caller's own account (usage is a property of the provisioner) and that other IDs yield 404. It adds meaning beyond the schema without over-explaining.
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 states a precise action and resource: 'Returns how many accounts you have provisioned and the billable count that follows from them.' It clearly distinguishes this from list/get account tools by focusing on usage/billing, and even clarifies the billable unit. An agent understands exactly what this tool computes versus siblings like 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?
The description implicitly conveys usage context: it is for retrieving usage/billing numbers, and explicitly warns that account_id must be the caller's own account (any other id returns 404). However, it does not name alternative tools or state when not to use this tool, such as 'use list_accounts to enumerate accounts instead'. That explicit exclusion is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that this is a mutation (readOnlyHint=false), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds valuable behavioral context beyond annotations: it explicitly defines the allowed role transitions (ADMIN ↔ MEMBER), the last-owner restriction, and that ownership transfer is handled elsewhere. This informs the agent about edge cases and operational constraints not covered by annotations.
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 concise and well-structured. It front-loads the core action, then provides necessary constraints and context, and ends with the endpoint. No redundant information; every sentence adds value. It's appropriately sized for a simple patch operation.
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?
For a simple role-change operation, the description covers the key aspects: what it does, the allowed values, the crucial ownership edge case, and the alternative pathway. It doesn't mention return values, but there is no output schema to explain, and the operation is straightforward. The annotations further cover idempotency and non-destructiveness. Minor omissions like error messages or permissions are not critical for basic invocation.
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?
The description adds meaning to the `account_role` parameter by specifying it can only be `ADMIN` or `MEMBER` and clarifying that `OWNER` is not accepted. While the schema's `AccountRole` definition already explains the enum and its non-assignability for setting, the description reinforces it and adds the 'between ADMIN and MEMBER' simplification. For `account_id` and `member_id`, the schema provides adequate descriptions, so the description doesn't need to elaborate. Given schema coverage of 67% and the added semantic clarity, this exceeds the baseline.
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 explicitly states the action: 'Changes a member's `account_role` between `ADMIN` and `MEMBER`'. It identifies the resource (member) and the endpoint. It distinguishes itself from `beel_put_owner` by clarifying that OWNER is not assignable here and that ownership transfer is a separate operation. This clearly sets it apart from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: it states that OWNER is not assignable here and directs the user to the dedicated `PUT /v1/accounts/{account_id}/owner` endpoint for ownership transfer. It also notes the last OWNER cannot be demoted, giving a clear constraint for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint false (write), openWorldHint true, idempotentHint true, destructiveHint false. The description aligns and adds substantial behavioral detail: it discloses that null only clears description, that numbering fields are rejected post-issuance, the exact error codes for default unmarking, and the no-op behavior for non-defaults. It also provides a guardrail resource link. This far exceeds the minimum and provides crucial operational nuance.
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?
The description is long but well-structured: it opens with the core partial-update rule, then covers the nuanced default_series behavior, then the endpoint, a guardrail warning, and a pointer to further docs. Every sentence adds necessary detail for correct usage; no fluff. It is somewhat dense but organized in clear paragraphs, deserving a 4 rather than a 5 due to its length.
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?
Given the complexity of partial updates, numbering restrictions, and default-series handling, this description covers all critical aspects. It mentions specific error codes, the no-op case, the guardrail resource, and directs to docs for exhaustive rules. Since there is no output schema, it appropriately explains what to expect only implicitly, but the behavioral rules are thorough. For a patch operation with many edge cases, this is complete.
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?
The input schema already provides rich descriptions for each field, including null semantics and restrictions (e.g., description can be null, active cannot be deactivated if default). The tool description adds value by clarifying which fields are 'numbering fields' (code, format, counter_reset, initial_number) and that only description supports explicit null clearing. It also explains the default_series handoff behavior in the context of the boolean parameter. This goes beyond the schema, though it doesn't enumerate every parameter individually—the schema carries that load, so a 4 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 description states a specific verb ('Updates') and resource ('series'), and clearly explains the partial-update semantics ('only the fields present in the body'). It distinguishes itself from a full PUT by describing what happens to omitted fields and nulls. This is unambiguous and differentiates it from sibling patch tools like beel_patch_invoice.
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?
The description provides clear context on when to use this tool and important usage constraints: it explains the default_series behavior, the specific error when trying to unmark a default, and points to the PUT endpoint for handing over the default. It also mentions that numbering fields are rejected after invoices are issued. It does not explicitly contrast with a full PUT for general updates, but it implies that PUT would be the alternative for replacing all fields. This is strong guidance, only missing an explicit 'use PUT when you want a full replace'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint=true, readOnlyHint=false), the description explains that repeating the call when the member already owns the account returns 204 rather than failing, and explicitly states the auth limitation (session-only). This adds valuable operational behavior not captured in annotations.
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?
The description is well-organized into three paragraphs, front-loading the core action and then covering edge cases and alternatives. It is informative without being verbose, though it could be trimmed slightly for a more compact definition.
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?
The description covers authentication requirements, idempotency behavior, the distinction from transfers, and provides an alternative endpoint. For a mutation tool with no output schema, it leaves little ambiguity about what the operation does and under what conditions it can be used.
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?
The input schema already provides descriptions for both account_id and member_id, so the description adds little new parameter-level detail. It clarifies the role of the body ('the member in the body') but does not exceed the schema's existing coverage. Baseline 3 is appropriate given schema coverage.
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 clearly states the action: 'Makes the member in the body the account's OWNER and steps the calling owner down to ADMIN', and explicitly contrasts it with a transfer. This distinguishes it from other account management operations without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage context: available only from a signed-in dashboard session, not via API keys, and names the alternative (claim token via POST /v1/accounts/{account_id}/claim-tokens) for integrations. This gives clear when-to-use vs. when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds significant context: the state machine, irreversibility of issuing, and the fact that SENT can be undone but ISSUED cannot. No contradiction with annotations; the description enriches behavioral understanding beyond the structured hints.
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?
The description is structured logically: purpose, transitions, exclusions, endpoint, guardrails, and pointers to docs. It is not overly terse but each sentence serves a function, and the front-loaded purpose ensures relevance. A minor deduction for length, though none of it is fluff.
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?
Given the complexity (state machine, fiscal constraints), no output schema, and a rich annotation set, the description covers all essential elements: allowed transitions, rejection behavior, separation of fiscal acts, and pointers to detailed guardrails and docs. An agent can invoke this tool correctly and understand its boundaries.
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 67%, and the schema itself provides detailed parameter semantics (status transitions, sent_at, payment_date, payment_method). The tool description adds behavioral context (e.g., rejection rules) but does not introduce new parameter-level meaning. This meets the baseline for decent schema coverage; the description complements rather than compensates.
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 ('Sets the commercial status of an invoice') and immediately enumerates the exact allowed transitions, distinguishing this tool from fiscal operations like issuing and voiding. It explicitly names sibling tools (beel_issue_invoice, beel_void_invoice) by their purpose, making selection unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states valid transitions and that 'any other transition is rejected.' It clarifies that issuing/voiding are not handled here and points to fiscal guardrails and exhaustive documentation. It also gives the endpoint, providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description elaborates on numerous operational nuances beyond the annotations: the mode is never inferred from the environment, PROD behavior depends on card-on-file, errors like 402 and 403, idempotency (no second checkout/charge, already_active flag), and the ability to cancel a pending switch-off. This is far more than the simple flags (readOnlyHint=false, destructiveHint=false) provide. The only discrepancy is with idempotentHint=false, but the description accurately explains the actual idempotent-like behavior.
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?
The description is lengthy but each paragraph covers a distinct aspect: core operation, mode behavior, idempotency, and switch-off cancellation. The first sentence front-loads the main purpose. While it is thorough, it could be condensed without losing essential detail; it is not overly verbose but is on the edge of being long. Therefore, a 4 is appropriate.
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?
The tool has no output schema, so the description takes full responsibility for conveying expected outcomes. It covers success indicators (already_active, scheduled_deactivation_cancelled), error conditions (402, 403), and payment/checkout flow. It also explains the interplay with the nested route and idempotency. No critical behavioral aspect seems missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already includes detailed descriptions (coverage 67%), the description adds substantial meaning: it explains why 'environment' must be explicit and its impact on AEAT registration, the derivation and behavior of 'idempotency_key' (auto-generated vs. explicit, 24-hour collapse), and the purpose of 'success_url'/'cancel_url' including why plain string format is necessary. These insights go well beyond the schema definitions.
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: 'Switches an existing company (NIF) on'. It clearly states the action and distinguishes it from the opposite operation (deactivation, evidenced by the sibling 'beel_deactivate_by_id'). The mode is explicitly clarified as being carried in the body, adding precision. This leaves no ambiguity about what the tool does.
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?
The description provides contextual guidance: it explains the immediate vs. checkout-required behavior for TEST vs. PROD, the billing-subject requirement, and the cancellation of pending switch-offs. These conditions imply when the tool is appropriate. It does not explicitly name alternatives to avoid using, but the tool's role is clear given the sibling list. The guidance is sufficient but not as explicit as a 'use this when...' directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: false and idempotentHint: true, but the description adds substantial behavioral detail: raising is only possible while unclaimed, billing is unaffected, OPERATE requires a signed fiscal representation for invoicing, and the 'manage_accounts' entitlement is required. It also describes the endpoint. No contradiction with annotations; the description enriches them.
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 compact and front-loaded. The first sentence states the main action, followed by concise constraints and the entitlement requirement. It ends with the endpoint, which is useful. Every sentence adds value; no filler. The structure is logical and scannable.
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?
For a mutation tool with no output schema, the description is complete. It explains the effect, the conditions for raising/lowering, billing implications, the special requirement for OPERATE, the required entitlement, and the endpoint. The input schema provides the enum details, so nothing essential for correct invocation is missing. Given the complexity of the operation, this is thorough.
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?
The schema has 0% parameter description coverage (based on context signals), so the description must compensate. The description explains the semantics of access_level extensively: what NONE, VIEW, OPERATE mean via the constraints and the fiscal representation note. It does not explicitly describe account_id, but that is self-evident as the account identifier. The description adds meaning beyond the schema, though it could explicitly name the parameters.
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 clearly states the action: 'Updates the access_level you keep over an account you provisioned.' It names the specific resource (access level on a managed account) and the verb 'updates'. It also immediately distinguishes itself from related tools by clarifying the unique constraints around raising vs lowering, which prevents confusion with tools like beel_end_management or beel_put_owner.
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?
The description provides context on when this tool is appropriate: when you need to change your own access over a provisioned account, with specific rules about raising only while unclaimed. It does not explicitly name alternative tools, but the constraints and entitlement requirement give clear guidance on the intended use case. It lacks explicit exclusions or 'use this instead' statements, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=true) but the description adds significant behavioral context: token validity of 30 days, invalidation of previous token on re-issue, rejection of mismatched email, and the side effect of handing over account ownership. It goes well beyond the annotations and discloses critical side effects.
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?
The description is relatively long but every sentence serves a purpose—core action, usage variants, invalidation behavior, alternative, and entitlement. It is front-loaded with the primary action and structured logically. Slightly verbose but not wasteful.
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?
For a sensitive operation like claim token issuance, the description covers usage scenarios, side effects, invalidation, and alternatives. It does not explicitly mention the HTTP endpoint (but that's in the description as 'POST /v1/accounts/{account_id}/claim-tokens') and omits idempotency behavior (schema covers). It lacks an explicit statement about return values, but no output schema exists. Given the complexity, it's fairly complete.
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 only 33% (account_id lacks a description), so the description compensates by explaining the semantics of email in detail (required when no holder, must match existing holder) and the body's purpose. It doesn't elaborate on language, but the schema does. It omits idempotency_key details, but the schema covers that. Overall, it adds value for the key parameter.
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 clearly states the action ('Issues a single-use claim_token and the claim_url') and the resource (claim token for an account holder). It also distinguishes itself from the related invitation tool by explicitly noting that adding a further person should use invitations, avoiding confusion among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: send email when no holder exists, omit body to re-issue, and details the rejection of mismatched emails. It also directs to the alternative 'POST /v1/accounts/{account_id}/invitations' for adding further people, and states the required entitlement, covering both use and non-use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating readOnlyHint=false and idempotentHint=false, the description adds significant behavioral context: 'Not atomic: each invoice is processed in its own transaction, and since issuing is irreversible, the ones already issued stay issued if a later one fails.' It also mentions per-invoice reporting and the endpoint. This goes well beyond the annotations and is crucial for an agent to understand side effects.
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 two tightly written paragraphs plus a single endpoint line. It front-loads the core purpose, then adds caveats and exclusions, then the endpoint. Every sentence carries essential information with no repetition or filler. This is a model of conciseness without under-specification.
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?
For a batch mutation tool with non-atomic semantics, the description covers all essential guidance: what it does, per-invoice reporting, irreversibility, exclusions, and the HTTP endpoint. It complements the schema (which details parameters) and annotations (which flag write behavior). Nothing critical is missing for an agent to invoke it correctly.
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 67%, and the schema itself provides detailed descriptions for 'operation', 'new_status', 'invoice_ids', and 'payment_date'. The description adds little beyond restating the operations and mentioning the 50-invoice limit (already in schema maxItems). While it does not harm, it does not meaningfully enhance parameter understanding beyond what the schema already provides.
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 precise statement: 'Applies one operation — ISSUE or STATUS — to up to 50 invoices of this company and reports, invoice by invoice, which succeeded and which failed.' It clearly identifies the resource (invoices), the action (batch operation), and the scope (company). It also differentiates from sibling operations like pdf-archive, deliveries, and exports, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when not to use this tool: 'Downloading PDFs, sending email and exporting are not operations of this batch: use `pdf-archive`, `deliveries` and `exports`.' It also warns about irreversibility and non-atomicity, which guides an agent on whether to use this batch tool vs. single-invoice alternatives. This is explicit and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations (which are generic). It discloses error semantics ('code already taken answers 409'), automatic default assignment for the first series, a warning that numbering can never be rewritten, and points to fiscal guardrails. This is rich, cautionary information an agent needs before calling.
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 front-loaded with the core action, then a warning block, then a pointer to docs. Every sentence earns its place: the unique-code rule, the format/reset coupling, the auto-default behavior, and the guardrail reference. No redundant filler, and the structure aids quick scanning.
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?
Given that there is no output schema, the description compensates by noting the 409 response, the automatic default, and pointing to docs for exhaustive rules. It also includes the endpoint. For a creation tool with complex parameter interactions, this is sufficient for an agent to proceed correctly.
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 description coverage is 67%, so some slack exists. The description adds value: it explains the uniqueness requirement for `code` (linking to 409), and the relationship between `format` and `counter_reset` (e.g., 'ANNUAL reset needs a year token'). These are not in the schema defs and help a caller construct valid arguments.
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 precise verb and resource: 'Creates an invoice series under a company (NIF).' This clearly differentiates it from siblings like beel_create_invoice or beel_create_company, and the mention of NIF aligns with the company_id parameter. The purpose is unambiguous.
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?
The description provides concrete usage constraints: unique series code, the dependency between counter_reset and format tokens (e.g., 'MONTHLY reset needs {MM} and a year token'), and behavior for the first series. It also directs the agent to beel_docs_search for exhaustive rules. It does not explicitly contrast with patch or get variants, but the constraints give clear guidance on when creation is valid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true and readOnlyHint=false, so the description correctly aligns with them and adds significant behavioral context: the soft-delete nature, the proforma status transition, and the explicit guardrail that issued invoices are never deleted. It discloses side effects and points to a dedicated resource for fiscal rules, going well beyond what annotations provide.
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?
Every sentence earns its place: the core action, the soft-delete detail, the issued-invoice alternative, the proforma side effect, and the pointer to guardrails. It is front-loaded with the essential purpose and then layers necessary constraints. No filler or redundancy.
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?
For a destructive tool with no output schema, the description covers all critical operational aspects: the conditions under which deletion applies, what happens to proformas, the guardrails, and where to get exhaustive rules. An agent knows exactly what to expect and how to proceed. Nothing essential 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?
The schema covers both parameters with 100% coverage, including a detailed description of company_id (explaining NIF, context derivation, and 403 behavior). The tool description adds no additional parameter-specific meaning, which is acceptable given the schema quality. The baseline 3 applies because the schema carries the semantic burden, and the description does not need to repeat it.
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 clearly states a specific action: 'Deletes a draft invoice of this company' and immediately clarifies it is a soft delete ('marked as deleted rather than removed'). It explicitly distinguishes this from voiding issued invoices, differentiating it from siblings like beel_void_invoice. The scope (draft only) is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: only for draft invoices. It gives an exclusion condition (issued invoices) and points to the alternative (void endpoint) with a concrete API path. It also explains the proforma-reversion behavior and directs to guardrails and docs for exhaustive rules. This fully informs an agent when to pick this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations offering only readOnlyHint=false and openWorldHint=true, the description carries full behavioral burden and delivers richly: it discloses that this is 'a fiscal act' consuming numbering from the template's series, may 'be issued and sent', and 'consumes the period that was pending' advancing next_generation. It also adds security behavior for company_id (undisclosed NIFs returning 403) and a dedicated fiscal guardrails section. No contradiction with annotations — openWorldHint=true is consistent with the disclosed side effects.
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?
Core function is front-loaded in the first sentence, followed by the high-value fiscal and occurrence-semantics warnings, then the when-not-to-use branch. Bold headers and short paragraphs aid scanning. It is moderately long and the guardrails section references external resources (beel://guardrails/...) that lean on a docs pipeline, but every sentence earns its place for a fiscal operation with real consequences.
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?
For a 3-param side-effecting operation with no output schema, coverage is strong: side effects, occurrence semantics, security behavior on company_id, idempotency defaults, and routing away from the wrong tool are all present. The only notable gap is that the response/return value is unspecified, which matters a bit more because there is no output schema. Even so, an agent can correctly invoke and reason about this tool.
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?
Despite 67% schema coverage (recurring_invoice_id has no schema description), the description adds deep meaning: company_id is 'the only source of context' with the BeeL-Active-Company header playing no part, plus the 403-on-unreachable behavior. idempotency_key gets an exceptionally thorough treatment covering the derived-default and the 24-hour collapse of deliberately identical operations. Only recurring_invoice_id lacks explicit parameter text, but the surrounding context ('this recurring template') makes its role clear, so the gap is minor.
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 ('Runs the generation of this recurring template immediately, out of its schedule') that goes well beyond a tautology of the name. It also distinguishes this from the creation of an extra invoice, explicitly naming the alternate path (derivations), so an agent can tell it apart from siblings like beel_create_invoice_derivation and beel_skip_recurring_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('brings the upcoming occurrence forward') and when-not-to-use ('For an extra invoice outside the calendar, do not use this endpoint') guidance, naming the alternatives (create a normal invoice, or use POST /v1/companies/{company_id}/invoices/derivations). It also clarifies how manual generation, skipping and the scheduler each consume exactly one occurrence, which directly helps the agent decide between this and beel_skip_recurring_invoice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses expiration (five minutes), HTTP method restriction (only GET), polling semantics (202 until 200), and specific error codes (400 INVOICE_NOT_ISSUED_NO_PDF). It also details security behavior around NIF existence disclosure in the parameter description, going well beyond the readOnly/idempotent hints in annotations.
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?
Three short paragraphs, each serving a distinct purpose: return value, polling behavior, and error handling. No fluff, front-loaded with the primary function, and every sentence earns its place.
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?
For a read-only retrieval tool with no output schema, the description covers all necessary aspects: URL behavior, expiration, polling decisions, error conditions, and the alternative for drafts. Combined with the annotations, it is fully actionable with no missing critical information.
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%, so the baseline is 3. The tool description itself adds no parameter semantics beyond what the schema already provides, though the schema's company_id description is exceptionally detailed. No additional value from the description itself.
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 (Returns) and resource (temporary pre-signed URL for invoice PDF), and clearly differentiates from the preview endpoint by naming it as an alternative. The endpoint path is included for precise identification, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to poll (202), when to expect 400 for drafts, and points to the preview endpoint as the alternative for drafts. This gives an agent clear decision guidance on when to use this tool vs. the preview, exceeding mere context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety is known. The description adds valuable behavioral detail: it explains the scope is per-person, not per-credential, describes 404 conditions (including 'another user of this same account'), and highlights security implications ('reads the traffic of your privileged keys too'). It also clarifies the effect of the timestamp parameter on the search window. These insights go well beyond the annotations and are crucial for correct and safe usage.
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 compact and front-loaded: the first sentence states the core purpose, followed by a clear 404 note, a security caveat, and the endpoint. Each sentence earns its place, and the bolded emphasis highlights the key scoping rule. There is no fluff, and the structure guides the reader from purpose to caveats to endpoint efficiently.
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?
The tool has 3 parameters, a rich set of annotations, and no output schema, so the description must carry the return-value information. It does so by stating 'Returns the full detail (bodies and headers)'. It also covers error semantics (404), the security scope, and the optional timestamp behavior. Everything an agent needs to call this tool correctly and interpret its result is present. The description is fully adequate for the tool's complexity.
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 each parameter already has a description. The description adds extra meaning: it explains that account_id 'authorizes the call; it does not widen what you can see', and that timestamp 'narrows the search window around that instant so the detail also works for logs older than the default window'. These are non-obvious behaviors that the schema does not convey. The request_id is simply called a correlation identifier, which the schema already states. This adds value beyond the raw schema, earning a 4.
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 clearly states what the tool does: 'Returns the full detail (bodies and headers) of a request made by you, with any of your API keys in this environment'. It specifies the resource (a request log entry) and the exact scope (traffic from the caller's own keys). It also contrasts with the sibling list tool implicitly by calling itself 'the widest read the logs:read scope opens', distinguishing it from a simple list operation. It is unambiguous and specific.
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?
The description provides context on when to use this tool: it is the detail view for request logs, and it emphasizes that the account_id 'authorizes the call; it does not widen what you can see', guiding the agent on its limitations. It also notes that 'a key holding only logs:read reads the traffic of your privileged keys too', which is a caution about security implications. However, it does not explicitly name the sibling tool (beel_list_request_logs) or state 'use this instead of the list tool when you need full bodies/headers', so the contrast is implied rather than direct. Still, it gives clear situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavior: irreversibility, asynchronous PDF/VeriFactu submission, and that a 200 only means accepted, not registered with AEAT. It also flags fiscal guardrails with resource pointers. This goes well beyond the structured fields and preempts common misuse.
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 well-structured: it opens with the core purpose, then the async caveat, then the endpoint, then fiscal guardrails as a warning block. Every sentence carries substantial information; the use of bullet points for guardrails improves scannability. Despite its length, it is tightly packed with essential facts and no filler.
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?
Given the complexity (irreversibility, async behavior, fiscal obligations) and the absence of an output schema, the description covers all necessary operational aspects: what it does, how to handle failure, why it may not reach AEAT, and where to find exhaustive rules. The parameter schema handles all argument details, so nothing essential is missing for correct invocation.
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?
Input schema coverage is 100%, so all five parameters (company_id, invoice_id, wait_for_pdf, idempotency_key, attach_source_invoices) are already fully documented in the schema with descriptions. The tool description does not add parameter-specific meaning beyond what the schema provides, so the baseline of 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?
The description opens with a precise verb and resource: 'Finalizes a draft invoice of this company: assigns its definitive number from the configured series and makes it immutable.' It clearly distinguishes the operation from siblings like beel_void_invoice and beel_create_corrective_invoice by stating its exact role and irreversibility. The purpose could not be misread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to call it (on a draft invoice) and points to guardrails for when an invoice can still be changed and what to do once it cannot. It also mentions that PDF and VeriFactu submission are asynchronous, setting expectations for the call. It directs to beel_docs_search for exhaustive rules, giving a clear escalation path. Alternative operations (corrective invoice or void) are named implicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral details: always paginated, empty page for accounts with no companies, ordering by primary company, and exclusion of invoice series. It also flags a fiscal guardrail resource. No contradiction with annotations.
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 well-structured and concise: main behavior first, then exclusions, endpoint, and guardrail pointer. No wasted sentences; every part earns its place. The warning is clearly delimited and the pointer to docs avoids unnecessary verbosity.
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?
For a read-only list operation with fully documented parameters and safe annotations, the description covers all essential aspects: response nature (paginated, empty page), ordering, search and include behavior, what's omitted, and access control. It also points to guardrails and exhaustive docs, ensuring agents have a way to get more detail if needed.
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. The description adds value by explaining search semantics (case-insensitive over NIF, legal name, trade name) and what include=readiness provides, and reinforces account_id's role in access control. This goes beyond the schema's concise descriptions, though not by a huge margin.
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 clearly states the tool returns a page of companies belonging to the account, ordered with primary company first. It names the specific resource (companies) and scope (account path), and explicitly mentions what is not included (invoice series), setting it apart from sibling list tools and the series endpoint.
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 directs users to a separate endpoint for invoice series, indicating when to use something else, and points to guardrails and docs for exhaustive rules. However, it does not explicitly contrast with other list tools (e.g., list_customers) or state 'use this when you need companies of an account' beyond the description itself. Still, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnly/idempotent, but the description goes far beyond: it discloses that every attempt is recorded (including REJECTED and QUEUED statuses), that sorting is by sent_at descending with sent_at absent while QUEUED, and that the account comes from the path while the environment comes from the credential. These behavioral details are not derivable from annotations alone.
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 well-structured: the main purpose is front-loaded, followed by key behavioral details and endpoint. Each sentence adds distinct value (status semantics, sorting, scoping, read-only) with no redundancy or fluff. It is appropriately sized for the tool's complexity.
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?
For a 9-parameter list tool with no output schema, the description covers the essential operational behaviors: what is recorded, status semantics, sorting, filtering, scoping, and read-only nature. Pagination is largely left to the schema, but the combination of description and schema is sufficient for an agent to call it correctly.
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% with thorough parameter descriptions, so baseline is 3. The description adds semantic context for sent_at (moment handed over, absent when QUEUED) and clarifies account_id sourcing (path vs. credential), enriching parameter meaning beyond the schema. It also lists filterable parameters, reinforcing their purpose.
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 clearly states the verb 'Returns' and the resource 'emails the system recorded on behalf of the account', specifying the path categories (invoice deliveries, verification, onboarding). It distinguishes itself as a list operation (vs. the singular beel_get_email_delivery) and explicitly notes it only reads history, differentiating from send tools.
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?
Provides clear context on when to use the tool (to read email history, filter by type/status/recipient/entity) and states it does not send/resend, implying when not to use it. However, it does not explicitly name alternative tools for those cases, so it stops short of full exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint false, etc.), so the description carries the full burden—and it excels. It discloses atomicity (issue:true fails together), state transitions (proforma preserved, moves to CONVERTED), error semantics (422 vs 409), side effects (new invoice with source_proforma_id), and the VeriFactu policy resolution. No contradiction with annotations; it enriches them significantly, painting a complete behavioral picture an agent needs to avoid mistakes.
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?
The description is long but structured: a clear lead sentence, then a paragraph on the conversion process, error list, endpoint, a warning callout for fiscal guardrails, and a pointer to docs. Every section earns its place, and the critical operational details are front-loaded. The only minor deduction is that the warning about guardrails could be integrated earlier, but overall it is well-organized and not bloated.
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?
For a complex fiscal operation with no output schema, this description is exceptionally complete. It covers the input conditions, the exact outcome, error scenarios, atomicity, idempotency, and fiscal guardrail resource. It also links to docs for exhaustive rules, ensuring an agent knows where to get more detail. Nothing critical is missing for correct invocation—only the actual response format is omitted, but that's acceptable given the absence of an output schema and the pointer to docs.
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?
The input schema already provides detailed descriptions for issue and verifactu_enabled (covering defaults and overrides), and the description adds a concise note on issue:true's atomic behavior. For idempotency_key, the schema explains the blind retry behavior; the description doesn't add much there, but that's acceptable since schema coverage is 75%. The description adds value precisely where it matters most—highlighting the issue flag's side effects—without redundancy.
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 precise verb+resource statement: 'Converts an accepted proforma of this company into a real invoice.' It immediately distinguishes from siblings by specifying the input status (ACTIVE), the output type (STANDARD DRAFT invoice), and the linkage (source_proforma_id). This is far more specific than vague alternatives like 'create_invoice' and leaves no doubt about its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use: only for accepted proformas in ACTIVE status, and even clarifies that EXPIRED proformas are still convertible because they remain ACTIVE underneath. It covers what happens on failure (422 errors) and idempotency (409 on second call), and points to a dedicated guardrails resource for the state machine. It also implies alternatives by directing to docs for exhaustive rules, effectively guiding the agent on boundaries without being redundant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only `readOnlyHint=false`, `openWorldHint=true`, `idempotentHint=false`, `destructiveHint=false` given, the description carries the behavioral burden and pays it generously. It discloses ownership semantics (NIF registered under the account holder, never the caller), side effects that never happen (never switches an existing company on, never opens a checkout on 402), activation/seed behavior, idempotency-collapse behavior, and environment aliasing. This substantially exceeds what annotations alone communicate, with no contradiction against them.
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?
The description is long, but the tool is complex and every sentence earns its place — purpose is front-loaded, then side effects/errors, then guardrails are explicitly demoted to pointers rather than inline duplication. The ⚠️ block is a good structural device. It borders on dense but stops short of redundant; the only mild criticism is that some error detail (e.g., specific error codes) is repeated between the prose and the schema $defs.
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?
Despite the absence of an output schema, the description is remarkably complete for a tool this complex. It covers the create-vs-activate distinction, series seeding with per-environment isolation, billing and ownership consequences, all relevant error codes, idempotency behavior, and points to documentation resources for exhaustive rules and worked examples. Nothing an agent needs to call it correctly is missing; the docs pointers appropriately defer the long tail.
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 67% and the schema's nested $defs (Address, TaxInfo, CompanyNumbering, Environment) are richly self-describing, so the baseline is at least 3. The description layers real semantic value on top: it explains the activate/numbering coupling, that `aeat_environment` is ignored when `activate: false`, the idempotency_key collapse semantics, and the backwards-compatibility alias for the old field name. A strong addition, though the deepest parameter detail still lives in the schema itself, which 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 description opens with a specific verb, resource and scope: "Creates a company (NIF) under the account in the path" — then immediately separates the two distinct acts of creating the profile and activating it, and names what activation seeds (three default invoice series). Endpoint is given explicitly. This clearly distinguishes it from siblings like beel_create_customer, beel_create_series, and beel_create_invoice, so an agent can tell it apart without inspecting those schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is explicit and actionable. It names the alternative door for switching an existing NIF on (`POST /v1/companies/{company_id}/activations`), states when a `numbering` block is rejected (`activate: false` → `NUMBERING_REQUIRES_ACTIVATION`), enumerates the error conditions (409 for existing NIF, 402 without billing), and routes to `beel_docs_search` for exhaustive rules via the fiscal guardrails block. Both when-to-use and when-not-to are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=true, and the description adds substantial behavioral context: invoice retention, the 403-on-retry-without-key quirk, conditional removal timing based on Live/Test, and endpoint details. It also flags fiscal guardrails, giving the agent full awareness of side effects and constraints.
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?
The description is detailed, but every sentence earns its place: the core purpose is front-loaded, followed by exclusions, idempotency, endpoint, and guardrails. While it is longer than the average tool description, the density of actionable information justifies the length, and it is well-structured with clear separators.
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?
For a destructive tool with multiple error codes, timing rules, and idempotency complexities, the description covers all essential aspects: when deletion is allowed, error responses, invoice retention, the effect of Live/Test status, and the idempotency-key behavior. It even includes the endpoint and a pointer to exhaustive docs. No output schema exists, but the description mentions expected response codes (204, 400, 403, 409), which is sufficient for an agent to interpret results.
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?
The input schema already covers company_id at 100% with a rich description, including the exclusive-source-of-context behavior and 403 semantics. The tool description reinforces this with the same 'only source of context' note and adds the context that a missing or unreachable NIF yields 403. This adds value beyond the schema without repeating it unnecessarily.
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 ('removes') and resource ('company (NIF)') and explains the effect ('stops appearing and stops being billed'). It clearly distinguishes this from sibling delete tools that target invoices, customers, or other entities, leaving no ambiguity about what resource is acted upon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditions for when the tool can and cannot be used, listing three distinct 409/400 error scenarios and the idempotency-key requirement. It also explains the timing difference between Live and Test deactivations, and points to guardrails and docs for further guidance. This is comprehensive and prescriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds substantial context beyond that: no scope required, never cached (Cache-Control: no-store), `name` resolution via `trade_name ?? legal_name` with null until onboarding, and the purpose of the `credential` object for adaptive clients. No contradictions.
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?
The description is well-structured: it leads with the main purpose, then adds behavioral details and a closing note on the credential object. It is a bit verbose, but every sentence contributes unique information. The endpoint at the end is a helpful reference. Slightly longer than necessary, but efficient.
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 parameters and no output schema, the description fully covers what an agent needs: what the tool returns, how to interpret success/failure, caching behavior, and field resolution rules. It leaves no ambiguity about when or how to call it, and the lack of an output schema is compensated by a thorough explanation of the response.
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?
There are zero parameters and the schema is empty, so the baseline is 4. The description does not need to elaborate on parameters, but it explains the meaning of response fields, which is indirectly useful for understanding the input-less invocation. No additional parameter semantics are needed.
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 states a specific verb ('Returns') and resource ('the identity of the authenticated principal'), enumerating the fields (email, name, logo, language, credential). It distinguishes itself from every other operation by requiring no scope, making its unique purpose unmistakable. The endpoint is even given as a concrete reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts this with all other operations ('Unlike every other operation') and clarifies when to use it: to confirm a credential works (200) vs not (401) and to learn which account a credential belongs to. It also explains how `BeeL-Active-Company` does not affect `account_id`, giving clear boundary conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the tool's behavioral traits beyond annotations. It explains the destructive nature (NIF can't issue/correct invoices after switch-off), the scheduling mechanism with `effective_at`, the refund policy ('Nothing is refunded'), and idempotency (`already_scheduled: true`). It also clarifies that sealing releases the NIF for another account in Live. This thoroughly supplements the annotations (destructiveHint: true, idempotentHint: true) and provides no contradictions.
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 detailed but well-organized, front-loading the core action in the first sentence. It then logically explains the scheduling nuances, edge cases, and authorization requirement. Each sentence adds essential information, with no fluff or redundancy. Despite its length, it is appropriately scoped for a complex operation with varied modes and timing behaviors.
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?
The description is complete for the tool's complexity without an output schema. It covers the operation, mode-specific behavior, scheduling details, `effective_at` semantics, no-op and idempotency cases, authorization requirements, and the endpoint. It does not explicitly list error codes, but the schema mentions 403 for unauthorized/existence, and the description's auth requirement covers that. An agent has all necessary information to correctly invoke and interpret the response.
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?
The description adds significant meaning for the `environment` parameter by explaining how Live vs. TEST/PROD affects scheduling and the presence of `effective_at`. This goes beyond the enum description in the schema. For `company_id`, the description does not add much beyond the schema, but the overall operation is clear. The schema description for `company_id` incorrectly says 'being switched on' instead of 'off', and the description does not correct this, but it's a minor issue since the tool description consistently says 'switch off'. The added environment semantics justify a 4, above the baseline 3.
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 clearly states the tool's purpose: 'Switches the company (NIF) off in the mode given by `environment`'. It specifies the verb (switch off), the resource (company/NIF), and the scope (the given mode). It also clarifies that the other mode is untouched, distinguishing it from activation tools like beel_activate_by_id. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when and how to use the tool. It explains the difference between Live (scheduled) and TEST/PROD under enterprise (immediate), states the requirement that 'Switching off in Live requires being the billing subject of the account', and describes edge cases like already-scheduled and no-op. It also implicitly contrasts with deletion ('sealed rather than deleted'), helping agents choose this over a destructive delete. The instructions are concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, idempotent, open-world), the description discloses critical behaviors: partial deletion with 200 response even when nothing is deleted, internal retention for tax purposes, identifier release, and the contrast with deactivation. It also explains the response body structure via customers_deletion. No contradiction with annotations.
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?
The description is relatively long but every paragraph adds essential detail for a destructive bulk operation. It is logically structured: first the partial-deletion behavior and response, then the per-deletion semantics, then the delete-vs-deactivate distinction. It could be slightly tightened, but the density of information justifies the length.
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?
Given the complexity (bulk partial operation, response semantics, comparison with deactivation), the description is remarkably complete. It covers operation behavior, response code rationale, per-deletion semantics, and the difference from deactivation. There is no output schema, but the description explains the response body sufficiently. No missing details that would prevent correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters with descriptions, but the tool description adds substantial meaning: `company_id` is the only context source (ignoring the BeeL-Active-Company header), and it explains 403 behaviors for unreachable or non-existent NIFs. The `ids` parameter's semantics are enriched by the description of partial deletion. This goes well beyond the schema's simple 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 clearly states the verb ('Deletes'), the resource ('customers listed in `ids`'), and the scope ('from this company (NIF)'). It also distinguishes the operation from its alternatives by explaining the partial nature and contrasting with single-delete and deactivate semantics. This makes the tool's purpose unmistakable even among many siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts deleting with deactivating via PATCH active:false, explaining when each is appropriate and the consequences (identifier release vs. retention). It also states that customers with invoices cannot be deleted and will return HAS_INVOICES, giving clear conditions for use. This is more than enough guidance for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint and idempotentHint, so the description need not repeat them. It adds valuable behavioral context: only auth_type=API_KEY traffic is recorded, cursor pagination behavior, default 30-day window, and the subtle point that account_id does not widen the result set. No contradiction with annotations; the description deepens understanding of the tool's semantics.
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?
The description is long (four paragraphs) but each section adds essential information: scope, exclusions, environment, pagination, and endpoint. It front-loads the primary purpose and uses bold for key constraints. While verbose, it avoids redundancy and is well-organized into logical blocks. Slightly longer than ideal but effective.
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?
For a tool with 10 parameters and complex filtering behavior, the description covers all necessary contextual elements: the exact scope, environment handling, auth_type restriction, pagination mechanism, default time window, and the role of account_id. It also mentions the expected response cursors (next_cursor/prev_cursor) despite lacking an output schema. No critical gaps exist for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (90%), but the description adds significant meaning to parameters: api_key_id can be any of your keys in the environment (not just the authenticating one), account_id is authorization only and does not widen scope, and cursor is opaque with directional navigation. It clarifies defaults for from/to and the meaning of only_errors (status >= 400), going beyond the schema's basic 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 clearly states the exact resource and scope: 'Returns the history of public API requests made by you, with any of your API keys in this environment.' It differentiates from the sibling beel_get_request_log by being a list operation and clarifies the person-centric axis. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states what it does (lists your API request history) and what it does not do (does not return other users' traffic, does not widen scope via account_id). It gives practical guidance for environment switching ('use a key from that environment') and clarifies that api_key_id is a filter, not default. This fully informs an agent when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: the catalogue is static, shared across credentials, independent of account/NIF, and effective before any NIF exists. It also explains the deliberate exclusion of 0% VAT and the rationale for keeping the 5% rate, which are non-obvious behavioral traits an agent should know. No contradiction with annotations.
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 well-organized: the first sentence states the core purpose, the second provides usage and invariants, the third dives into VAT nuances that materially affect interpretation, and the endpoint is appended. Every sentence carries necessary information — the VAT 0% explanation prevents a costly mistake. It is comprehensive without being redundant, and the most critical info is front-loaded.
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 must fully convey the response shape. It lists all returned categories (VAT, IGIC, IPSI, IRPF, equivalence surcharge, exemption reasons) and even flags the 'exemption_reasons' field name. It covers caveats (0% handling, IGIC difference, 5% rate retention). An agent can call this tool and interpret the response correctly. Nothing critical 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?
The tool has zero parameters, so schema coverage is trivially 100% and there is nothing to document. Baseline for 0 params is 4. The description adds no parameter-specific semantics (there are none) but instead explains the data returned, which is not parameter documentation. Given the baseline rule, 4 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 description opens with a precise verb and resource: 'Returns the tax regimes and percentages that Spanish law allows on an invoice.' It enumerates the exact content (VAT, IGIC, IPSI, IRPF, equivalence surcharge, exemption reasons) and distinguishes itself from tax-related siblings like beel_get_tax_configuration and beel_update_tax_configuration by clarifying this is a static catalogue independent of any account or NIF. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use it to validate a rate before sending it, or to build your own picker instead of hard-coding the percentages.' It also clarifies the catalogue works before the first NIF exists and is the same for every credential, giving clear context. While it doesn't name a specific alternative to exclude, the use cases are unambiguous and self-contained, which is sufficient for a read-only metadata tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description goes far beyond: it explains immutability of `nif`, `entity_type`, `legal_form`, the AEAT census re-validation for `legal_name`, the write-only nature of most fields, the return type `CompanyData` that excludes the request body, and the exact live/test restrictions. This fully discloses side effects and response behavior without contradicting any annotation.
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?
The description is long but well-structured: it starts with the core purpose, then immutability, live/test rules, return behavior, and finally guardrails. Each paragraph carries essential information and the guardrail section is clearly separated. It could be slightly tightened (e.g., merging some repetitions about write-only fields), but the length is justified by the complexity of the rules.
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?
Despite lacking an output schema, the description covers return semantics (what `CompanyData` carries, which fields are read back from other endpoints), references the exact endpoint (`PATCH /v1/companies/{company_id}`), and points to exhaustive documentation. It also mentions the account/context derivation and the `BeeL-Active-Company` header non-involvement, which is essential for correct invocation. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already provides descriptions for each field (NIF format, immutability notes, etc.), the description adds critical operational semantics: it distinguishes the six fields writable from Test on a Live company, clarifies that the rest are write-only and answered with `422`, and specifies that sending a field its current value is never a change. This goes beyond the schema's per-field descriptions and directly guides parameter choice.
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 states a specific verb ('Updates') and a precise resource ('editable fields of a company (NIF)'), and immediately scopes the field set to `UpdateCompanyRequest`. It differentiates from related operations by focusing on the patch semantics and by detailing immutability rules, which makes it unambiguous among the sibling tools that also write company data (create, activate, deactivate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context: it enumerates which fields are writable from Test on a Live-activated company, which fields trigger AEAT re-validation, and what error (`422 FISCAL_IDENTITY_LIVE_ONLY`) results from disallowed writes. It also directs the agent to `beel_docs_search` for exhaustive rules, and the guardrails pointer adds a resource-specific prerequisite. This clearly conditions invocation on credential mode and field selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals key behavioral traits beyond the annotations: it applies the NIF's configuration 'as it stands now', enforces a 3-attempt limit (`retry_count`), and returns 400 for non-retryable events. It also explains idempotency behavior in detail (derived key collapses identical operations for 24 hours, custom key separates them), which is valuable for understanding side effects. No contradiction with annotations (readOnlyHint false, idempotentHint false) — the description actually enriches them.
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 efficiently structured: the main purpose is front-loaded, followed by usage guidance, retry conditions, and the endpoint. Every sentence contributes essential information; there is no redundancy. The use of bullet-like formatting (line breaks) improves readability without adding fluff.
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?
The description covers all critical aspects needed to correctly invoke the tool: the purpose, when to use it, eligibility conditions, error behavior (400), and idempotency handling. It also includes the endpoint, which aids in understanding the operation. Given that no output schema is provided, the description sufficiently prepares the agent to call the tool safely and correctly.
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?
With 100% schema description coverage, the parameters are already well-documented. The description adds extra semantic value by linking event_id to `retry_available` (clarifying eligibility) and by giving practical advice on idempotency_key (when to set a custom one). This goes beyond the schema's basic definitions, but doesn't fully redefine the parameters, so a slight bump above baseline is warranted.
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 states a specific verb ('Reprocesses'), a specific resource ('a payment event'), and the precise context ('whose automatic invoicing did not complete'), making the tool's function unmistakable. It also distinguishes itself from siblings like beel_get_payment_event and beel_generate_payment_event_draft by focusing on retry, not retrieval or draft generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use the tool: 'Use it after fixing what caused the failure', and provides a clear exclusion: only events with `retry_available` equal to `true` are eligible, otherwise a 400 is returned. It even advises reading `retry_available` instead of deriving retryability from `status`, which is direct, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark the operation as non-read-only and non-idempotent, but the description adds crucial context: idempotency by external_ref (contradicting the generic idempotentHint but not conflicting—it explains conditional idempotency), reactivation of previously ended accounts, the default access_level of NONE, and the effect of omitting email. The description also discloses entitlement requirements. It goes far beyond the annotations.
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?
Although lengthy, every sentence serves a purpose: main behavior, variants, edge cases, entitlement. The structure front-loads the claim_token concept and then systematically explains optional fields and their consequences. No repetition or filler; it is as concise as possible given the complexity.
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?
For a complex provisioning operation with an endpoint, multiple optional parameters, and no output schema, the description is complete: it explains what the response contains (claim_token, company_id), prerequisites (entitlement), idempotency, reactivation, and default behaviors. Nothing an agent needs to decide whether and how to call it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has descriptions for many nested fields, but the description adds semantics that the schema alone does not: it explains the two integration branches, the dependency of OPERATE on tax_profile, the idempotency use of external_ref, and the different outcomes (claim_token vs. none). This compensates for the 50% schema coverage by clarifying behavioral implications of each parameter.
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: 'Provisions a new account on BeeL'. It clarifies behavior around claim_token, email, tax_profile, and access_level, and distinguishes it from related actions like creating a company or claim token by explicitly stating it provisions an account and sets up invoicing readiness. This leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use guidance: it explains the two integration modes (with email for a holder, without email for no person), when to include a tax_profile (for invoicing readiness), the requirement that OPERATE access demands a tax_profile, and the idempotency/reactivation behavior. It also mentions the manage_accounts entitlement, effectively telling the agent when it can be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral details: full replacement semantics, server-side resolution, the requirement that apply_by_default cannot be true when enabled is false, side effects of setting enabled to false (stops sending invoices, starts deregistration), and that it does not deactivate the company. This goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) and adds significant value.
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 structured and front-loaded with the core purpose. Each sentence adds value: the replacement semantics, the writable fields, the constraint, side effects, and the endpoint. The fiscal guardrails warning is clearly separated and the pointer to docs avoids redundancy. Despite being long, it is efficient and well-organized.
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?
For a configuration update tool, the description covers everything an agent needs: what is replaced, what is required, what cannot be set, the side effects, the endpoint, and pointers to additional documentation. It also explains the error condition (422 APPLY_BY_DEFAULT_REQUIRES_ENABLED). Even without an output schema, the behavior of the response is implied (server-side resolved). Complete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already describes the parameters (enabled, apply_by_default, and company_id), the description enriches them by explaining the full-replacement behavior, that both are required with no default, and the dependency between them. It also clarifies the meaning of company_id as the sole source of context, including security nuance (NIFs in other accounts are never disclosed).
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 begins with 'Replaces the VeriFactu configuration of a company (NIF)' — a specific verb and resource. It clearly states it is a full replacement, not a partial merge, and mentions the endpoint. This distinguishes it from the read operation (beel_get_verifactu_configuration) and other update tools like beel_update_tax_configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool (updating VeriFactu configuration) and when not to (it does not deactivate the company; releasing the NIF is a separate DELETE action). It provides fiscal guardrails and points to beel_docs_search for exhaustive rules, giving clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![beel-mcp MCP server](https://glama.ai/mcp/servers/beel-es/beel-mcp/badges/card.svg)](https://glama.ai/mcp/servers/beel-es/beel-mcp)

Score Badge

Copy to your README.md:

[![beel-mcp MCP server](https://glama.ai/mcp/servers/beel-es/beel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/beel-es/beel-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/beel-es/beel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server