BeeL MCP server

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), the description discloses what actually happens: 402 CHECKOUT_REQUIRED with checkout_url, 409 NIF_LIMIT_REACHED, 403 NOT_BILLING_OWNER, charge/credit behavior, and the fact that a pending switch-off commits the NIF to the next billing cycle. It also explains idempotent replay across the route and its nested predecessor, which the annotations alone could 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.

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

The core purpose is front-loaded in the first sentence, and the remainder is organized under clear headers (Modes and billing, Idempotency and pending switch-offs). It is long, but nearly every line carries operational information; a few billing-edge sentences are dense but not wasteful.

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

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

For a mutation tool with nested body, no output schema, and monetary side effects, the description is unusually complete: it covers modes, billing prerequisites, idempotent retry semantics, pending-switch-off interactions, and the specific error codes an agent may need to handle. Nothing material required 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.

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

At 67% schema coverage the description adds real meaning: it explains that environment is always taken from the body (not credentials), that billing_period only matters when a checkout is opened (default MONTHLY), and that repeating a call opens no second checkout. The idempotency_key consequences are also spelled out, compensating for the partial schema coverage.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ("Switches an existing company on in the mode carried in the body") and immediately clarifies that the mode is explicit rather than inherited from credentials. This is precise enough to distinguish it from beel_deactivate_company, though it never names that sibling explicitly to confirm the relationship.

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

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

The Modes and billing section explains in detail when each mode applies, when a checkout opens (no card on file), and which errors (403 NOT_BILLING_OWNER, 422 ANNUAL_PLAN_NOT_AVAILABLE) gate the call. It stops short of explicitly contrasting with alternative tools like beel_deactivate_company or beel_provision_account, but the operational conditions are exhaustive.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description still adds real context beyond them: what actually breaks (production AEAT invoice submission), what is explicitly untouched (company activation and non-VeriFactu issuing), and the 400 failure mode. Minor tension worth noting: a repeat call on an already-cancelled representation errors rather than succeeding, which is idempotency of state rather than of response, and the description could say so more directly.

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

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

The lead sentence is front-loaded and the two bolded bullets make effect and failure mode scannable at a glance. The trailing "BeeL API endpoint /docs" line is reference material rather than invocation guidance, so it is slightly surplus, but nothing is genuinely wasteful.

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

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

For a single-parameter destructive mutation with no output schema, the description covers the operational consequence, the untouched surfaces, and the error case, with annotations carrying the safety flags. What is left thin is recovery: it does not tell the agent which tool regenerates the representation or what the caller must do to restore production issuing.

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

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

There is a single parameter and schema description coverage is 100%; the schema already explains that company_id is a UUID, is not the NIF, and is the sole source of context including the 403 behaviour for unreachable companies. The description contributes nothing further about the parameter, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

"Cancels the active AEAT representation of a company" gives a specific verb plus a specific resource, which separates it from beel_generate_representation, beel_get_representation and beel_download_representation_document that share the same domain. It stops short of naming those siblings explicitly, so the differentiation rests on the verb rather than on an explicit contrast.

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

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

The description supplies one concrete precondition: with no active representation the call is rejected with 400, framed as "a state transition, not a delete-if-present". That is useful when-not guidance, but it never states when an agent should reach for this tool instead of the sibling representation tools (generate / get / download) or what path restores the revoked state beyond the vague "until a new document is generated and signed".

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description discloses the claim-state precondition that gates raising access, that billing is unaffected at any level, and that OPERATE additionally requires a signed fiscal representation. These are exactly the non-obvious constraints an agent needs before invoking a destructive mutation.

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

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

Four bolded bullets, each front-loading a distinct concern (raise/claim, billing, OPERATE, entitlement), followed by the endpoint line. No filler sentences and no repetition that doesn't reinforce a constraint.

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

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

For a destructive two-parameter mutation with no output schema, the description covers preconditions, cost implications, and permission requirements thoroughly. It does not describe what the response returns or what happens to entities created under OPERATE after a downgrade, but with no output schema that omission is minor.

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

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

With 50% schema coverage, the description carries real weight: it explains the raise-vs-lower asymmetry of access_level and the billing neutrality, and the schema's AccessLevel enum already enumerates NONE/VIEW/OPERATE with meanings. Some redundancy with the schema's enum description costs a point, and the account_id ownership/404-indistinguishability behavior is only in the schema, not the description.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first line names a specific verb and object ('Updates the access_level you keep over an account you provisioned') plus the exact endpoint PATCH /v1/accounts/{account_id}/access-level, which immediately separates it from sibling mutations such as beel_end_management or beel_put_member_grant. An agent can tell what changes and whose access is affected 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.

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

It gives a sharp when-condition and when-not: raising is only possible while the account is unclaimed, and after claim only the holder can raise it. The entitlement requirement ('requires manage_accounts') further scopes applicability. It stops short of naming an alternative tool (e.g. end_management) for relinquishing access entirely, so there is no explicit alternatives routing.

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

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

Adds substantial behavior beyond the annotations (destructiveHint/idempotentHint/openWorldHint): atomic issuance with rollback, the fact that a failed issue leaves the proforma `ACTIVE` and nothing created, the terminal `CONVERTED` status and preservation of the `PRO-...` number/PDF, and that a second call never creates a second invoice. The enumerated error codes with meanings (SERIES_NUMBER_COLLISION, PROFORMA_NOT_CONVERTIBLE, PROFORMA_ALREADY_CONVERTED) are exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the one-sentence purpose, then organized under bolded bullets for what converts, the proforma's fate, `issue`, and errors — easy to scan. Slightly long, and the trailing guardrails pointer is a separate concern appended to the definition rather than integrated.

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

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

For a destructive, atomic conversion mutation with no output schema, it covers preconditions, side effects, rollback, idempotency behavior and failure codes. The only real gap is what the response body contains (the new invoice id/number), which the agent would need to chain a follow-up call.

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

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

Schema coverage is 75%, so the baseline is already high, and the description still adds meaning for `issue`: it explains the atomic numbering/issuance flow and the specific failure mode (`400 SERIES_NUMBER_COLLISION`) that callers should expect. `idempotency_key` and `company_id` are only covered by the schema, not the description, but their schema text is thorough, so the gap is small.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('converts an accepted proforma into a real invoice') and pins down the result shape: a `STANDARD` draft linked via `source_proforma_id`. That is clearly distinct from siblings like beel_create_invoice, beel_issue_invoice and beel_create_invoice_derivation.

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

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

Gives the precondition for use ('only proformas in status `ACTIVE`'), including the useful edge case that an `EXPIRED`-looking proforma is still `ACTIVE` underneath. It does not explicitly name an alternative sibling or say when to prefer `issue: true` versus calling beel_issue_invoice afterwards, so the alternative routing is left implicit.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, but the description goes far beyond them: it discloses non-atomicity with per-row failure, idempotency keyed on `external_ref` rather than the `Idempotency-Key`, file and row limits, the NIF_LIMIT_REACHED blocking rule, and that claim tokens appear in this response and nowhere else. It also warns that a failed row leaves earlier rows provisioned and that billing settlement can happen via re-upload.

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

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

The definition is long but front-loaded and sectioned under headings that let an agent scan to the relevant risk (idempotency, limits, activation, claim tokens). A few sentences restate the same point — the billing surprise is mentioned in the activation section and implied again earlier — but nothing is pure filler.

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

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

For a mutation tool with nested objects, no output schema, and only 2 top-level parameters, the description supplies the return-side facts an agent would otherwise lack: `statistics.accounts_created`, `own_company_customers`, per-row `BLOCKED` reasons, and `claim_link_already_issued` versus a fresh token. Nothing needed to call it correctly, or to persist what it returns, is missing.

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

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

With schema coverage at 50%, the description carries meaningful weight: it explains that `customers_file` applies to every account including pre-existing ones and is idempotent by tax id, that `apply_customers_to_own_company` targets the in-focus company and surfaces in `own_company_customers`, and that the files are declarative so a larger population is imported in passes. It adds less on `idempotency_key` and `accounts_file` preamble handling than the schema already does, so not a 5.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource — provisions the managed accounts described in an uploaded file, switches them on in Live, leaves them ready to invoice — and then pins the semantics with an equivalence to `POST /v1/accounts` per row plus activations. An agent can tell this apart from `beel_provision_account` (single account) and `beel_preview_account_import` (no effects) 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.

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

Explicitly routes away from this tool when no writes are wanted: 'to see what this would do without writing anything, use `POST /v1/accounts/imports/preview` ... the import is never governed by a boolean flag.' It also names the recovery path (fix the cause and re-upload the same file) and states that there is no resume, so both when-to-use and when-not-to-use are covered.

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

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

Goes well past the annotations: 30-day token lifetime, single-live-token semantics, the fact that re-issuing silently kills the previous link, and the required `manage_accounts` entitlement. It also discloses the destructive consequence that the annotations only flag abstractly (destructiveHint=true), and the mismatch rejection behaviour rather than implying silent replacement.

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

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

Front-loads the one-line purpose, then three labelled bullets that each carry a distinct decision-relevant fact (body semantics, lifetime/invalidation, alternative endpoint, entitlement). No filler, and the endpoint line is a compact pointer rather than prose.

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

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

For a mutating, non-idempotent-looking operation with no output schema, the description still tells the agent what it produces (`claim_token` and `claim_url`), how long it lives, what it invalidates, what permissions it needs, and which sibling to use instead. Nothing needed 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.

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

Adds real meaning for `body.email` (create-vs-reissue branching, mismatch rejection) and for retry semantics, on top of a schema that is already 67% documented. It never mentions the `language` parameter, which the schema covers but the top-level description leaves entirely to the nested definition.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (issues a single-use `claim_token` plus the derived `claim_url`) and immediately names the outcome it enables: the holder sets a password and takes ownership. It also distinguishes itself from the nearest sibling in the same sentence family by explicitly ruling out the invitation flow.

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

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

Gives explicit branching conditions: send `email` when the account has no holder, omit the body to re-issue for an existing holder, and use `POST /v1/accounts/{account_id}/invitations` instead when a holder already exists. It also states the rejection condition (an email differing from the current holder's), so the agent knows what not to attempt.

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

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

Annotations already declare the mutation/idempotency profile, yet the description goes well beyond them: it discloses that no billing charge is started, the 403 (must be billing subject) and 402 (no billing) outcomes, the 409 duplicate path that returns `error.details.company_id`, and the 422 postal-code failure that creates nothing. It also explains that activation seeds three default series in `aeat_environment` and that numbering does not carry across environments.

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

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

Purpose is front-loaded in one sentence, then bolded bullets group the distinct behaviors (activate, numbering, billing, duplicates, addresses), followed by the endpoint and prerequisite guardrail resources. It is long but nearly every line carries a distinct rule or error code; the length is justified by the tool's complexity rather than padding.

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

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

For a mutation tool with deep nested objects, no output schema, and real side effects (NIF registration, series seeding, billing eligibility), the description covers the risky paths and pre-links three guardrail resources. The remaining gap is that nothing is said about what the call returns on success (e.g., the created company identifier or activation state), which forces the agent to discover the response shape empirically.

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

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

Schema description coverage is 67% and the nested body schema is already very rich, so the baseline is 3; the description earns above that by adding semantics the schema does not: the 402/403 billing gates tied to `activate`/production NIF, the duplicate-NIF behavior, and the Spanish postal-code constraint applying to both `address` and `legal_representative.address`. It does not touch `default_main_tax` or `default_irpf_rate`, leaving those entirely to the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource ("Creates a company under the account the request resolves to") and immediately disambiguates ownership semantics (NIF registered in the account holder's name, never the caller's). It also explicitly separates itself from the activation path ("This endpoint never switches an existing company on: that is POST /v1/companies/{company_id}/activations"), so an agent can distinguish it from the beel_activate_company sibling without opening either schema.

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

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

The description states the condition that selects the alternative path: activating an existing company goes to the activations endpoint, and `activate: false` is the way to defer that. It also states the coupling rule that `numbering` is only valid when the same request activates. It stops short of routing against other create-style siblings (beel_provision_account, beel_create_customer) or advising when a company should be created at all, so context is clear but not exhaustive.

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

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

Annotations declare destructiveHint=true, but the description goes far beyond that: it names the resulting status of the original (VOIDED vs RECTIFIED), states the original's PDF is untouched, explains series auto-creation, numbering collision behavior, the 0-total auto-PAID rule, and the four-year deadline. These are exactly the side effects an agent needs before committing a destructive fiscal write.

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

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

It is well front-loaded and consistently structured with bold lead-ins per rule, so it scans well. But it is extremely long for a tool description, and several passages (IRPF/surcharge inheritance, SUPLIDO exclusion, series numbering) duplicate text already present in the input schema almost verbatim, so not every sentence earns its place.

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

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

For a high-stakes, many-parameter fiscal mutation with no output schema, the definition covers the full decision surface: modes, error codes with detail payloads, deadline computation, recipient correction, series behavior, and idempotency context. Nothing an agent needs in order 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.

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

Schema coverage is 75% and the description meaningfully extends it: it explains the TOTAL/PARTIAL contract for `lines`, the `series_id` default (never the original's series), the `recipient`-only-for-data-correction case with R4, and what `rectification_code` legally requires. It loses a point because the fiscal-inheritance paragraph largely restates what the `irpf_rate` and `equivalence_surcharge_rate` schema fields already document at length.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ("Issues a corrective invoice that amends the invoice in the path") and immediately disambiguates it from an edit of the original ("a new fiscal document with its own number, not an edit"). It also implicitly separates it from beel_patch_invoice and beel_void_invoice, which are the closest siblings.

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

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

It states when to use each mode (TOTAL vs PARTIAL), when not to use it at all ("A withholding is not a cause for a corrective: void the invoice and issue a new one without it"; a different recipient means void and reissue), and routes to alternatives for cases it cannot handle ("to fix an erroneous corrective, issue another one against the original invoice"). The prerequisite cases (AEAT-rejected original, exchange invoice F3) are also spelled out.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds genuinely useful behavior beyond that: omitting the key derives one from the request, which is safe for blind retries but collapses a deliberately identical second creation within 24 hours, so an explicit key should be set when needed. The NIF-validation guardrail pointer also signals a downstream invoice-submittability risk.

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

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

The definition is short and front-loads the operation before the idempotency detail and the guardrail pointer. The idempotency bullet is dense and somewhat awkwardly phrased, but every sentence carries relevant information.

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

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

For a create tool with a large nested schema and no output schema, the description is thinner than ideal. It omits what the response contains, how validation failures surface beyond the guardrail pointer, and how required fields such as legal_name and address interact with the customer type, leaving the schema to do most of the work.

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

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

Schema description coverage is 67%, so the schema already carries most parameter meaning, including the full body shape. The description adds cross-route idempotency-key semantics that are not fully captured in the schema, but it does not explain body fields such as legal_name, nif, or address, which are central to this create operation.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Creates a new customer under this company.' It is immediately clear what the tool does, but it does not distinguish this single-customer creation from siblings such as beel_create_customers_bulk or beel_create_customer_import.

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

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

There is no when-to-use guidance, no comparison to the bulk or import tools, and no prerequisites or exclusions. The 'Read before calling' pointer to a guardrail resource is a caution rather than guidance on when this tool is the right choice over alternatives.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, but the description goes further: it states exactly what is created, that existing tax identifiers are reported as duplicates rather than re-created, that over-limit files are rejected as a whole, and it enumerates the 400/413/422 codes. The one defect is the claim that 'Idempotency-Key' is 'required on this operation', which conflicts with the schema's 'Optional idempotency key' and could make an agent always set it.

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

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

The definition is front-loaded with the payload rules and organized into tight bolded bullets, so an agent can scan to the topic it needs. It is long, and the closing sentence about the import 'never being governed by a boolean flag' is defensive padding rather than information.

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

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

For a mutation tool with no output schema, the failure-mode coverage is unusually complete, but nothing describes what a successful response returns (created count, duplicate list, partial-failure reporting), which is exactly what the missing output schema would have provided. The internal inconsistency about whether the idempotency key is required also leaves the caller unsure of the correct request shape.

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

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

Schema coverage is 67%, so the schema already carries part of the burden, but the description adds real meaning for `source`: per-format file type, size and record caps, and the distinct error codes. It adds little about the `file` payload itself (encoding, header requirements, how an .xlsx body is expressed as a string), which is the parameter most likely to be misused.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource with scope: 'Imports customers into this company from an uploaded file.' It is also clearly separated from beel_create_customer, beel_create_customers_bulk, and beel_preview_customer_import, which would otherwise be plausible competitors.

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

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

It explicitly routes the agent to beel_preview_customer_import when no writes are wanted, and clarifies there is no boolean dry-run flag. It does not, however, say when to use this file import rather than beel_create_customers_bulk or beel_create_customer, which is the other realistic alternative an agent would weigh.

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

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

Adds substantial behavior beyond the annotations: full-batch atomicity with `422 BULK_VALIDATION_ERROR` and nothing persisted, the 200-vs-201 status distinction between dry run and real run, the scope of what validation covers (AEAT census, in-batch and existing duplicates, field formats), and that both modes return the same per-record report. This is exactly the failure-mode and side-effect context annotations cannot express.

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

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

Front-loaded one-line purpose followed by three tight, useful bullets; each earns its place by describing atomicity, mode semantics, and return consistency. Minor waste: the dry_run bullet partially duplicates the schema description, and the trailing guardrails warning plus endpoint line add bulk that could be trimmed.

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

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

For a mutation tool with a deep nested payload and no output schema, the description covers the key risk surface (atomic rejection, validation scope, dry-run safety, response consistency). The remaining gap is that the per-record report's structure is only alluded to rather than described, but the extensive $defs and parameter docs carry most of the payload burden.

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

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

Schema coverage is 75% and the dry_run parameter already carries a near-identical description in the schema, so the bullet mostly restates structured data. company_id and idempotency_key are not touched in the description, though the schema documents them at length. Baseline 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'Creates up to 500 customers of this company in a single call.' That clearly separates it from list/patch/delete operations. However it never names the single-record sibling beel_create_customer or beel_create_customer_import, so the agent must infer the bulk-vs-single choice from the tool name alone.

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

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

The dry-run bullet gives clear operational guidance (validate first, then create) and warns that the operation is all-or-nothing. But there is no explicit statement of when to prefer this tool over beel_create_customer for one record or beel_preview_customer_import for an import flow, which is the main routing decision an agent faces among these siblings.

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

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

Substantially exceeds the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true) by disclosing that the token is returned once and never readable again, that invitation_url is built from it, that send_email defaults to false so the caller must deliver the link, and exact 422 failure modes for null grants and OWNER roles. These are exactly the operational facts an agent needs and none are derivable from the annotation block.

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

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

Front-loaded with the verb and resource, then four tight bolded bullets keyed to the parameter names — easy to scan. A little of the content (the grants/null 422 rule, the send_email default) duplicates the schema descriptions nearly verbatim, so it is not maximally efficient, but nothing is padded.

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

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

With no output schema, the description correctly carries the return contract (token, invitation_url) and explains the delivery model, which is the biggest risk of misuse here. Gaps remain around duplicate/resend behavior for an already-invited email and around the destructiveHint=true annotation, which is not elaborated on.

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

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

With 67% schema coverage, the description still adds real meaning: the distinction between omitting grants, sending [], and sending an explicit null (422) is spelled out, and it explains the delivery consequence of send_email rather than restating its default. It also explains why grants are meaningless for ADMIN/OWNER, which the enum schema only hints at.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource — 'Creates a single-use invitation for a person to join the account' — with the 'single-use' qualifier and the role scoping making the operation unambiguous. It does not name the sibling invitation tools (beel_list_invitations, beel_get_invitation, beel_delete_invitation) to route an agent, so it stops short of full sibling differentiation.

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

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

It gives concrete when/constraint guidance: grants apply only to MEMBER, OWNER cannot be invited at all, and ownership transfer is explicitly redirected to PUT /v1/accounts/{account_id}/owner — a genuine alternative route. It also tells the caller when send_email should be flipped to true. It never says when not to create an invitation (e.g. re-inviting an existing member), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true; the description still adds real behavior beyond them: draft-by-default, asynchronous AEAT submission where a 2xx means PENDING rather than registered, and that a series collision fails without issuing anything or consuming a number. However, it does not explain the response payload (invoice id, number, status fields) or the interaction with idempotency, which matters for a tool marked idempotent.

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

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

Front-loaded: the core create/issue behavior is in the opening two sentences, then bolded sub-sections for Issuing, Document type, and Related. The trailing guardrail resource list is long but scannable and each entry names a distinct concern. Slight redundancy between the endpoint line and the prose keeps it from a 5.

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

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

For a tool with a very large nested body, no output schema, and fiscal side effects, the definition covers the material decision points (draft vs issue, doc type, collision, async submission) and points to guardrail resources for the deep fiscal rules it cannot inline. The remaining gap is the successful response shape beyond verifactu.submission_status, which an agent must guess before chaining further calls.

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

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

Schema description coverage is high (75%) and the nested body schema is extremely detailed, so the schema does most of the work. The description still adds meaning the schema does not: how options.issue_directly changes numbering/issuance, that PROFORMA ignores issue_directly and is born ACTIVE with a PRO- number, and the verifactu.submission_status return contract.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource ("Creates an invoice for this company") and immediately clarifies a scoping rule: issuer data comes from the company in the path. Additional sections pin down variants (draft vs issued, PROFORMA vs fiscal) and explicitly name the sibling endpoint used for copying, so an agent can distinguish it from beel_create_invoice_derivation, beel_create_corrective_invoice and beel_issue_invoice 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.

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

It states the default outcome (draft unless you ask to issue), how to switch (options.issue_directly), and routes to an alternative tool when the intent is copying an existing invoice (POST …/invoices/derivations, with its differing field set named). It also flags a failure mode (400 SERIES_NUMBER_COLLISION) that indicates when the caller should stop and contact support rather than retry.

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

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

On top of annotations that already flag destructiveHint=true and idempotentHint=true, the description adds the behavior that matters most: the operation is not atomic, issuing is irreversible, and partial failures leave already-issued invoices issued. It also discloses the 50-invoice cap and the per-invoice success/failure report shape, which are not derivable from 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.

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

The description is front-loaded with the core verb, then organized into bolded bullets for operations, limit, atomicity and related endpoints, so an agent can scan it quickly. The operations bullet largely duplicates the enum descriptions in the schema, which is the only wasted content.

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

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

With no output schema, the description compensates by explaining that results are reported invoice by invoice as succeeded/failed, and it covers the mutation's risk profile and size limit. It omits prerequisite conditions such as whether STATUS transitions are validated or which draft states are issuable, but the essentials for calling it correctly are present.

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

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

The description restates the ISSUE/STATUS semantics and the 50-item limit that the schema already documents, adding meaning mainly through the non-atomic partial-failure framing. It says nothing about payment_date (required for STATUS to PAID) or idempotency_key, leaving those entirely to the schema, which is consistent with the 67% coverage baseline.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Applies one operation to a set of invoices of this company') and enumerates the two supported operations, ISSUE and STATUS, so the agent knows exactly what the tool does. It distinguishes itself from the non-batch alternatives by naming the pdf-archive, deliveries and exports sub-resources, though it never names the single-invoice siblings (beel_issue_invoice, beel_set_invoice_status) that it most closely competes with.

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

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

It gives clear context for use: one operation across up to 50 invoice_ids, with an explicit exclusion list for PDF download, email delivery and export, which the agent should route elsewhere. It stops short of stating when a batch is preferable to single-invoice calls, so the choice between this tool and beel_issue_invoice/beel_set_invoice_status is left implicit.

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

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

Beyond the annotations (destructiveHint, idempotentHint, openWorldHint), the description discloses partial-failure semantics — invoices whose PDF cannot be attached land in `failures` and the message is still sent with the rest — which is real behavioral context an agent cannot get from the annotations. It also states no address is inferred from any profile, though it does not mention the destructive side effects of firing an irreversible external email.

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

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

The front-loaded first sentence is good and the bullets are scannable, but two of the three bullets duplicate schema constraints (minItems, maxItems: 200), and the trailing endpoint/URL line is metadata rather than guidance for the agent.

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

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

With no output schema, the description does the important work of naming the `failures` field and the still-sent behavior, which is exactly what an agent needs to interpret the result. Nesting and the cc/quota rules are left to the schema, which is reasonable given the tool's moderate complexity.

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

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

Schema coverage is 67%, so a baseline of 3 applies. What the description says about `recipients` and the 200-invoice limit largely restates the schema's minItems/maxItems and its recipients note, and it says nothing about `cc`, `subject`, `message`, `language`, or `idempotency_key` semantics.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource — sends one email carrying PDFs of several invoices as attachments — and the bullets scope it to a single message. It never names the sibling it is not, so an agent must infer the difference from beel_send_invoice or beel_get_invoice_pdf 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.

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

Usage is only implied by the constraints (at least one recipient, up to 200 invoice ids). There is no statement of when to choose this over beel_send_invoice for a single invoice, nor any prerequisite about the invoices needing to exist or be issued before delivery.

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

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

Annotations already declare a non-readonly, non-destructive, idempotent mutation, and the description goes well beyond them: it enumerates exactly what is copied (recipient, lines, payment method, series, observations) versus reset (number, status, dates, VeriFactu data, PDF), and names the failure mode 422 SERIES_INCOMPATIBLE_DOC_TYPE. It does not cover return shape or permission/auth requirements, keeping it short of a 5.

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

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

Front-loads the one-line purpose, then uses bullets for mode and series, and closes with a short pre-call reading list. The API endpoint line is mildly redundant but useful for debugging; overall there is little filler.

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

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

For a 3-parameter nested-body mutation with no output schema, the definition covers purpose, copy/reset semantics, series validation, and an error code, plus pointers to guardrail resources. The only meaningful gap is that it never says what the call returns (presumably the new draft invoice), which an agent may want before chaining.

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

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

With 67% schema coverage the description still adds real meaning for `series_id`: it defaults to the source's series but is validated against the copy's type, and a CORRECTIVE copy is born STANDARD. It also reinforces `from_invoice_id` as the untouched source. `company_id` and `idempotency_key` are left to their already-detailed schema text.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a draft invoice derived from an existing invoice of this company') and immediately scopes it with 'The source invoice ... is not modified.' It also rules out the adjacent operation by noting that proforma conversion is not a derivation mode, so an agent can separate this from beel_create_invoice and beel_convert_proforma_to_invoice.

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

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

Gives concrete pre-call routing: consult beel_rules_list with a domain or the beel://guardrails/<domain> resource for fiscal rules, and beel://guardrails/invoice-state-machine for status names and which tool performs each operation. It does not explicitly name beel_create_invoice as the alternative for building an invoice from scratch, so the when-not-to-use case is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds behavior the annotations cannot: the created object is returned with its `id`, omitted fields default silently, and specific failures surface as 409 PRODUCT_DUPLICATE for a reused `code` and 422 for an incoherent tax/surcharge pair — useful for planning retries and validation.

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

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

Purpose and return value are front-loaded in one sentence, then four tight bullets each covering a distinct decision point (required/defaults, code uniqueness, tax coherence, bulk alternative), followed by the endpoint and doc link. No sentence is filler.

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

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

For a mutating create with a nested tax object and no output schema, the description supplies the essentials: defaults applied on omission, the returned `id`, the two error classes an agent must handle, and where to go for bulk. It does not describe the rest of the returned product representation, but with no output schema that gap is minor rather than blocking.

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

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

Schema coverage is 67%, so the schema carries much of the load, but the description adds real meaning on top: `code` is unique per company and collides as 409 PRODUCT_DUPLICATE, and `equivalence_surcharge_rate` must be coherent with `main_tax.regime_key` or the request answers 422. It leaves `unit`, `description`, `default_price` and `irpf_rate` entirely to the schema, which is acceptable given those fields are documented there.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Creates a product or service in the catalog of the company in the path and returns it with its id', plus what a product holds (reusable defaults for invoice lines: name, price, unit, taxes). That scope cleanly separates it from beel_create_products_bulk, beel_patch_product and beel_list_products without opening any schema.

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

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

Gives concrete operating context: only `name` is required, omitted `category` becomes SERVICE and the product is created active. It also routes volume cases elsewhere ('Several at once: .../products/bulk creates up to 100 in one call'). It stops short of naming the sibling tool or stating when not to use this one (e.g. versus updating an existing product), so not a full 5.

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

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

Discloses non-obvious behavior the annotations cannot carry: per-row partial success, the fact that rejected rows are reported rather than failing the batch, and the surprising rule that a 201 is returned even when zero products were created, with 422 reserved for malformed requests. This is exactly the operational context an agent needs before retrying or parsing a response.

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

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

Front-loaded opening sentence, then two compact labeled bullets for partial operation and status codes, plus the endpoint line. No filler and nothing repeated.

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

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

For a mutating batch tool with no output schema, it covers failure modes, per-item independence and request-level rejection well. The one gap is the shape of the 'report' it references — with no output schema, the description could say what the per-item result contains, but overall nothing needed 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.

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

Schema description coverage is 67% and the description adds no meaning to any parameter beyond restating the 100-item cap already encoded as maxItems. The idempotency_key trap, company_id semantics and the nested product fields are explained only in the schema, so the description fails to compensate for the coverage gap.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Creates'), resource ('products in the catalog of this company') and a hard scope ('up to 100'), which cleanly separates it from the single-item sibling beel_create_product. An agent can pick the right tool from the first line alone.

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

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

The 'up to 100' limit implies bulk use versus beel_create_product, but the description never names that alternative or says when to choose one over the other. It gives thorough guidance on outcomes, not on tool selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description goes well beyond them: it explains that the cadence governs the step and not the first invoice, that `next_generation` is recomputed against today's calendar and missed periods are not generated, that `draft_in_advance` uses a fixed 5-day window with both options emitting on the scheduled day, and that VeriFactu is decided at issue time rather than stored on the template. These are non-obvious behaviors an agent could not derive from the schema or annotations.

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

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

Well front-loaded: one sentence of purpose, then bolded, scannable bullets for cadence, start date, drafts and VeriFactu, closing with the endpoint reference and a pointer to beel_rules_list. It is longer than it needs to be because the cadence and start-date bullets largely duplicate the `frequency` and `start_date` schema descriptions, which is repeated content rather than new value.

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

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

For a complex nested-object creation tool with no output schema, the description covers the hard parts — recurrence anchoring, generation suppression, draft review, VeriFactu timing — and defers line-level and tax mechanics to the rich schema. The notable gap is that it never says what creating the template returns (an id usable with beel_get_recurring_invoice), which matters when there is no output schema.

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

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

Schema coverage is 67%, and much of the description's parameter prose (frequency, start_date, draft_in_advance, preview_days) restates the schema property descriptions nearly verbatim, which per the scoring rules earns little credit. What it does add is synthesis — how cadence interacts with the first occurrence — plus the deprecation relationship between `draft_in_advance` and `preview_days`; the undocumented remainder (name, notes, send_automatically, email_configuration) is left to the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Creates a recurring invoice template under this company', and enumerates what the template carries (lines, recipient, series, payment) plus the recurrence. That distinguishes it in substance from beel_create_invoice and beel_generate_recurring_invoice_now, but it never names the sibling tools it is not, so an agent comparing siblings must infer the boundary.

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

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

Gives unusually concrete usage conditions: when to omit `frequency`, what a past `start_date` does, and the explicit migration workaround ('send a `start_date` of tomorrow ... so it is not invoiced twice'). It stops short of naming alternatives such as beel_patch_recurring_invoice for editing or beel_set_invoice_schedule for a one-off scheduled issue, so the exclusion side is implied rather than stated.

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

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

Annotations already declare write/destructive/idempotent/openWorld, so the bar is lower; the description still adds substantive behavior: the source invoice is not modified, an unreachable invoice is reported identically to a non-existent one (deliberate information hiding), and AEAT registration is decided by the company's regime at issuance rather than inherited. It does not discuss the response payload or what the created template exposes afterwards.

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

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

Front-loaded with a single defining sentence, then clean bulleted sections for source invoice, recurrence, and VeriFactu, followed by the guardrails pointer. Some content overlaps the schema text, but every block is scannable and none is filler.

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

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

For a derived-template creation with a nested body, no output schema, and destructive semantics, the description covers source requirements, recurrence semantics, and fiscal side effects well. The remaining gap is the result: it never says what comes back (template id, computed next_generation), and sibling routing is only implicit.

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

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

Schema coverage is a moderate 67% and the three top-level parameters (company_id, body, idempotency_key) are already well documented in the schema with the same wording the description reuses. The description usefully restates which recurrence fields are required vs. optional and how frequency maps to months, but that duplicates the schema's own field descriptions rather than adding new meaning.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Creates a recurring invoice template') plus the distinguishing mechanism ('taking its lines, recipient, series and payment data from an existing invoice, so only the recurrence has to be described'). That clause alone separates it from beel_create_recurring_invoice, which builds a template from scratch and must supply series/lines.

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

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

Gives real preconditions — the source invoice must belong to the company in the path, the cadence is deliberately not copied, VeriFactu is not inherited — and a 'Read before calling' pointer to beel_rules_list for fiscal guardrails. It stops short of an explicit routing statement naming the from-scratch sibling as the alternative when no suitable source invoice exists.

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

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

Annotations only declare the CRUD/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true); the description goes well beyond by naming concrete rejection modes (409 SERIES_FORMAT_OVERLAPS, 422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED, 409 duplicate code) and the cross-series uniqueness rule. It also discloses a non-obvious side effect: the first series of a document type becomes default even if default_series=false. That is exactly the behavior an agent cannot infer from annotations.

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

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

Front-loaded with the core action, then scannable bolded bullets keyed to parameters and failure modes, followed by prerequisites. Every bullet carries a distinct rule, but a few restate what the input schema already says about counter_reset and default_series, adding some redundancy.

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

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

For a create-mutation with nested request bodies and no output schema, the description covers validation rules, uniqueness collisions and default-series side effects, and it routes the agent to guardrail resources. It never says what the successful response contains (created series id/fields), which matters more here because no output schema exists.

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

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

Schema coverage is 67% and the schema is already verbose, but the description adds cross-parameter meaning rather than repeating definitions: format must contain {NUM}/{NUM:X}, and because counter_reset defaults to ANNUAL, a format without a year token must be sent with counter_reset: NEVER. It also explains default_series auto-promotion and the code-uniqueness constraint. Some of this duplicates the schema's own field descriptions, which keeps it from a 5.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line gives a specific verb and resource ('Creates an invoice series under a company'), and the following bullets pin down exactly what a series is in this domain (document_type, code, format, numbering). An agent can distinguish this from beel_list_series, beel_patch_series, beel_delete_series and beel_set_default_series without opening any schema.

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

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

The '⚠️ Read before calling' block tells the agent to consult beel_rules_list with a domain or the beel://guardrails/series-and-numbering resource first, which is real, actionable when-to-use guidance. It also states preconditions (a corrective invoice needs its own series). It stops short of naming sibling tools for the modify/default paths, so it is clear context rather than full alternative routing.

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

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

Goes far beyond the annotations: it discloses that each simplified invoice becomes VOIDED with EXCHANGED rather than being cancelled, that the exchange invoice itself cannot afterwards be voided, and that VeriFactu acceptance of every source is a hard gate with distinct 422 codes for pending vs rejected. This is exactly the consequence-level context an agent needs for a destructive, open-world operation.

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

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

Front-loaded with the one-sentence purpose and the corrective-invoice disambiguation, then organized into bolded bullets covering the issuance, the sources and VeriFactu. It is long, but nearly every line carries operational meaning; some error-code detail overlaps with the schema's own descriptions.

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

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

For a nested, 3-parameter, destructive operation with no output schema, the definition covers the trigger, the numbering, the side effects on sources, and the AEAT acceptance preconditions with actionable error codes. Nothing essential for a correct first call appears to be missing.

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

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

Schema coverage is 67%, and the description compensates well: it explains that the full invoice is numbered in series_id or the company default, that simplified_invoice_ids lines become the invoice lines in order with max 50 items, and that the recipient must be identified as a standard invoice requires. It does not touch the options/idempotency_key parameters, leaving those to the schema text.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Issues a full invoice in exchange for one or more simplified invoices') and immediately distinguishes it from the sibling corrective-invoice operation: 'It is not a corrective invoice: it documents the same operations again with the recipient identified'. An agent can route between beel_create_corrective_invoice, beel_issue_invoice and this tool without opening schemas.

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

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

Gives an explicit real-world trigger ('when the customer asks for an invoice with their details'), names the alternative it is not (corrective invoice), and points to prerequisite reading (beel_rules_list, beel://guardrails/verifactu-gates). Preconditions for the source invoices are enumerated with the exact failure code for each.

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

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

The description adds substantial behavior beyond annotations: the `secret` is returned only once and used to sign deliveries via `BeeL-Signature`; `test_delivery` is a one-off best-effort signed delivery that can be null; the account relationship options are explained; and hard limits plus duplicate-subscription side effects are disclosed. This gives an agent rich 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.

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

The description is front-loaded with the core action, then uses labeled bullets for key facts. Every bullet carries useful information (secret one-time return, test delivery semantics, account relationship, limits). It is slightly dense but well structured and free of obvious filler.

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

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

For a create operation with no output schema, the description compensates by explaining key response fields (`secret`, `test_delivery`), side effects, and limits. It does not describe the full response shape or authentication requirements, but those gaps are minor relative to the complexity of the tool.

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

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

Schema description coverage is moderate (67%), and the schema already documents all three parameters in detail, including `account_id`, `idempotency_key`, and the nested `body` fields. The description reinforces `events` and `account_relationship`, but adds little parameter-level meaning beyond the schema and does not mention `idempotency_key` directly.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Registers an HTTPS endpoint to receive notifications for the event types listed in `events`.' It is clear what the tool does and implicitly create-specific, but it does not explicitly name or differentiate from siblings like `beel_test_webhook_subscription` or `beel_patch_webhook_subscription`.

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

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

Usage is implied: create a webhook subscription with a URL and event types. The description adds caveats (10-subscription limit, duplicate URL behavior, best-effort test delivery) but never says when to use this tool versus alternatives such as testing an existing subscription or updating one. No explicit when-not guidance is provided.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it explains that data is sealed rather than removed, that invoices can be neither issued nor corrected until reactivation, that Live sealing releases the NIF for another account, that nothing is refunded, that `effective_at` is returned, and that a repeat call yields `already_scheduled: true` while switching off a never-activated mode is a silent no-op. It also discloses the billing-subject permission requirement.

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

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

Content is front-loaded with the core action followed by clearly headed sections for timing, repeats and permissions, so the agent can scan to the relevant part. It is on the long side and restates the mode-scoping idea in both the opening and the 'Sealed' bullet, but every paragraph carries operational information.

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

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

There is no output schema, yet the description names the response fields the agent will encounter (`effective_at`, `already_scheduled`) and explains when each appears. Combined with timing, idempotency and permission semantics, a caller has everything needed to invoke this mutation and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to `environment` by stating the switch-off applies only to that mode and leaves the twin untouched, which the schema's one-line 'Mode to switch the NIF off in' does not convey. The `company_id` permission behaviour (403 on unreachable or nonexistent companies) is already covered in the schema, so no extra credit there.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource, 'Switches the company off in the mode given by `environment`', and immediately scopes it: the other mode is untouched. The phrase 'Sealed, not deleted' implicitly separates it from the destructive sibling `beel_delete_company` and mirrors `beel_activate_company`, so an agent can place it 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.

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

It gives clear conditions for use: what happens in Live versus TEST/PROD-under-enterprise, that the Live switch-off is scheduled rather than immediate, what happens on repeat calls, and that Live requires being the billing subject. It stops short of explicitly naming the alternative tools (e.g. `beel_delete_company` for true deletion, `beel_activate_company` to reverse), which keeps it from a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds materially more: invoice retention after NIF removal, the primary-NIF guard, Test-vs-Live blocking differences, and the 403-instead-of-204 retry answer without an Idempotency-Key. The last point slightly qualifies the idempotentHint by exposing a retry failure mode, but it refines rather than contradicts it, so no contradiction is flagged; missing only a statement of required scopes/permissions.

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

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

The lead sentence states the effect up front and the bulleted blockers make scanning easy; every bullet conveys actionable information. It is on the long side and the guardrails warning is somewhat boilerplate, keeping it just short of a 5.

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

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

For a destructive single-parameter mutation with no output schema, the description covers side effects, blocking error codes, timing of deactivation-driven removal, and retry semantics, plus an endpoint reference and API docs link. An agent could call this correctly and predict the failure modes without opening anything else.

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

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

Schema description coverage is 100% and the company_id description already covers UUID format, account derivation, header irrelevance, and 403 nondisclosure, so the schema carries the parameter burden. The tool description itself adds little parameter-level meaning beyond mentioning that the company-scoped API can no longer resolve invoices once the NIF is removed, and points to beel://guardrails/multi-nif for selection rules.

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

Does the description clearly state what the tool does and how it differs from similar tools?

"Removes a company from the account: it stops appearing and stops being billed" gives a specific verb, resource, and observable consequence. It also implicitly separates itself from the sibling beel_deactivate_company by explaining that deactivation is a precondition rather than an equivalent action.

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

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

The description names the exact conditions that block the call (409 COMPANY_ACTIVE_IN_PRODUCTION, 409 COMPANY_HAS_INVOICES, 400 CANNOT_DELETE_PRIMARY) and explains the alternative path via deactivation being scheduled to end of paid cycle. Test vs Live divergence is called out explicitly, which is precisely the when/when-not guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered. The description still adds real value: it names the downstream consequence (future invoices render without a logo), confirms existing documents are untouched, and substantiates idempotency by stating a delete of an absent logo returns 204.

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

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

Three tight sentences: purpose first, then side effects, then the idempotency edge case, followed by a one-line endpoint/reference pointer. Nothing is redundant and the most decision-relevant facts are front-loaded.

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

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

For a single-parameter destructive delete with rich annotations and a fully documented schema, the description covers the blast radius and the no-op case, which is what an agent needs. The only gap is that error/response behavior beyond 204 is left entirely to the schema, so it stops short of fully complete.

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

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

Schema coverage is 100% and the single company_id parameter is documented in exceptional detail, including UUID format, context derivation, and the 403 non-disclosure behavior. The description adds no parameter meaning of its own, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

"Removes the logo of a company" is a specific verb+resource and the follow-on sentence scopes the effect to future invoice rendering. No sibling in the provided list handles logos, so differentiation is implicit rather than stated, which keeps it just below the top band.

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

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

Usage is implied by the narrow, self-evident purpose, and the description does clarify the temporal scope (afterwards vs. already-issued). However, it never states when to use this versus updating the company via beel_patch_company, nor any prerequisites such as permissions or confirming the logo exists.

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

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

Goes well beyond the supplied annotations by disclosing that deletion is a soft delete retained for tax records, that subsequent access returns 404, that the list filter never shows it, and that the NIF is released. It documents the 409 CLIENT_HAS_INVOICES and 400 REFERENCED_BY_RECURRING_INVOICE failure modes, which is exactly the behavioral context an agent needs for a destructive operation.

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

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

Front-loads the core action, then uses labeled bullets for meaning, identifier release, blockers, and the recurring-invoice constraint. The length is justified for a destructive operation, and no sentence is wasted.

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

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

For a destructive two-parameter tool with no output schema, the definition covers semantics, failure modes, alternatives, and side effects. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, and the company_id schema description already explains UUID, account context, and 403 behavior. The description adds little parameter-level meaning beyond restating the endpoint path, 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.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: deletes a company customer that has no invoices. It distinguishes the operation from siblings such as beel_patch_customer and beel_delete_customers_bulk by scoping it to one customer and to the no-invoices condition.

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

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

Explicitly names the alternative when deletion is blocked: set active to false via update instead. It also explains the recurring-invoice case with the exact 400 error, so the agent knows when not to call it and what to do instead.

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

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

Goes well beyond the destructive/idempotent hints by disclosing that the endpoint returns `200` with a body even on full failure, that successes and failures are mixed in `customers_deletion` with per-row statuses, and which status blocks deletion (`HAS_INVOICES`). It also spells out the underlying data semantics: internal retention for tax records, identifier release for NIF reuse, and invoice copies of recipient data.

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

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

The opening sentence carries the core action, and the headed sections are scannable and information-dense rather than padded. It runs long, but nearly every line (partial-result semantics, row statuses, delete-vs-deactivate) changes how an agent would call or interpret the tool.

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

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

With no output schema, the description takes on the burden of explaining return behavior and does so concretely: `200` with a `customers_deletion` body, per-row statuses, and the `HAS_INVOICES` case. For a destructive bulk operation, that is sufficient for correct invocation and result interpretation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to `ids` by explaining that each entry is processed independently and reported back with a status rather than aborting the batch. `company_id` is already exhaustively documented in the schema and the description correctly refrains from repeating it.

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

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Deletes the customers listed in `ids` from this company'), making the bulk scope explicit through the `ids` list. The 'Deleting is not deactivating' section additionally separates it from `beel_patch_customer` and by implication from the single-customer `beel_delete_customer`.

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

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

Gives clear when-to-use context: use it with a set of IDs, expect partial success, and expect `HAS_INVOICES` rows to be refused. It does not explicitly route single-customer deletions to `beel_delete_customer`, but the surrounding conditions are clear enough that an agent can pick correctly.

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

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

Annotations already declare destructive/not-read-only/idempotent, and the description adds non-obvious behavior on top: the exact state machine that gates success, the deliberate 404 that hides which resolved state applies, and the fact that revocation leaves the invitation visible in listings. Those are real operational details an agent cannot infer from the annotations or schema.

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

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

Front-loaded one-sentence purpose followed by two tight bullets, each carrying distinct information. The trailing BeeL endpoint and docs URL are boilerplate that does not help tool selection, which keeps it from a perfect score.

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

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

For a two-parameter, annotation-rich mutation tool this covers purpose, preconditions, failure modes, and post-state. The one gap is the success response shape (status code or body) — with no output schema present, a single clause on what a successful revoke returns would close the loop.

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

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

Schema description coverage is 100% and both parameter descriptions already spell out the cross-account 403/404 semantics, so the description adds nothing about `account_id` or `invitation_id`. Baseline 3 applies because the schema is doing all the parameter work.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb plus resource plus state constraint: 'Revokes a `PENDING` invitation, so its acceptance link stops working.' That distinguishes it cleanly from `beel_create_invitation`, `beel_get_invitation`, `beel_list_invitations`, and the other delete-family siblings without opening any schema.

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

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

It states a clear precondition and exclusion: only `PENDING` invitations can be revoked, and resolved ones (ACCEPTED/REVOKED/EXPIRED) cannot. It does not, however, name the alternative path an agent should take instead (e.g. listing or fetching the invitation first to confirm state, or creating a fresh invitation), so routing 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.

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description goes further by disclosing the soft-delete semantics and the fiscal-trail rationale, plus the non-obvious side effect on the source proforma's state. It does not describe the response body or any permission/error behavior beyond what the schema's company_id note already covers.

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

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

Front-loaded with the core action, then bulleted distinctions and a clearly marked 'Read before calling' block. The guardrails/resource pointers are useful but slightly tangential for a tool an agent already knows it needs; wording is otherwise tight with no filler.

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

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

For a two-parameter destructive mutation with no output schema, the description covers scope, alternatives, side effects on related records, and where to check fiscal rules. Nothing an agent needs to call it correctly or safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real constraint meaning for invoice_id: only draft invoices are accepted, and the proforma-linked case is called out. It does not add anything for company_id, which the schema already explains in detail.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Deletes a draft invoice of this company') plus the crucial scope restriction (draft only), and immediately clarifies that the record is soft-deleted rather than removed. An agent can distinguish it from beel_void_invoice without opening either schema.

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

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

Explicitly says issued invoices are never deleted and names the alternative endpoint/tool path (`POST …/{invoice_id}/void`) for them. It also documents the re-usable proforma case where deletion, not voiding, returns the proforma from CONVERTED to ACTIVE.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description still adds real value: it clarifies that only the schedule is destroyed (the invoice survives as a draft), specifies the 204 response for an unscheduled invoice, and notes the feature-flag independence. It stops short of covering authorization requirements or whether the prior schedule details are recoverable.

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

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

The effect and idempotency semantics are front-loaded in two tight sentences, which is the right ordering. The trailing guardrail block is longer than the substantive content, and its second bullet is a sentence fragment ('The status names, the proforma lifecycle, and which tool performs each operation') that conveys little on its own.

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

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

For a two-parameter destructive mutation with no output schema, the description covers the essential unknowns: what is removed, what remains, idempotent responses, and a pointer to the invoice state machine. Authorization/scopes and any side effects on related records are left unaddressed.

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

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

Schema description coverage is 100%, and the company_id field already explains UUID-vs-NIF, header independence, and the 403 behaviour for foreign or nonexistent companies. The description adds nothing further about the two parameters, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus the concrete outcome: the schedule is removed and the invoice returns to a plain draft, which distinguishes it from deleting the invoice itself. The contrast with the sibling that sets a schedule is made obliquely as 'the `PUT`' rather than by naming beel_set_invoice_schedule or beel_patch_invoice_schedule.

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

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

Usage is implied through the stated effects and the note that this call, unlike the PUT, does not require the `scheduled_invoices` feature, which helps an agent choose between the two. However, there is no explicit when-to-use/when-not-to-use statement naming the sibling tools, and the '⚠️ Read before calling' block points at guardrail resources without saying under what conditions this tool should be avoided.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a genuine business rule beyond annotations: the last OWNER is protected from removal, which signals an error path an agent should anticipate. It stops short of saying whether the member's grants are cascaded or removed.

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

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

The core behavior and the OWNER constraint are front-loaded in two tight sentences, and the endpoint reference is compact. The docs URL and endpoint restatement add marginal value but are not wasteful.

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

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

With no output schema and full parameter documentation in the schema, the description needs only to cover behavior and pitfalls, and it covers the key destructive-case constraint. Missing details such as cascade effects on member grants or required auth role keep it from being fully complete with a destructive mutation.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including the account_id scoping/403 behavior. The description only echoes the two path parameters through the endpoint line, adding no new meaning; baseline 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: it removes a member's access to the account, which is distinct from the sibling beel_delete_member_grant (grants) and beel_patch_member (editing). It does not explicitly contrast itself with those siblings, but 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.

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

The description states one important precondition — the account's last OWNER cannot be removed — which helps an agent avoid a failing call. However, it never says when to use this versus beel_delete_member_grant or beel_patch_member, nor what permission level is required to perform the removal.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the blast radius is exactly one company and sibling grants survive. It stops short of saying what happens when the grant does not exist, or what permission level is required.

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

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

Two tight sentences with the effect and scope front-loaded, followed by the API reference. The endpoint line slightly restates the three required parameters already in the schema, but it does anchor the agent to the docs for deeper questions.

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

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

For a destructive three-parameter mutation with no output schema and full schema coverage, the description covers what is destroyed and what is preserved, and annotations cover safety and idempotency. Missing only error-case behavior (nonexistent grant, insufficient permission) and confirmation of the empty response body.

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

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

Schema description coverage is 100%, including a detailed account_id note about 403 semantics, so the schema carries the parameter burden. The endpoint template in the description maps the three parameters onto path segments, which is minor reinforcement rather than new meaning. Baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (revokes) and resource (a member's grant over one company), and immediately bounds the scope: grants over the account's other companies are untouched. That scope sentence is what separates it from beel_delete_member (removes the membership entirely) and beel_put_member_grant (adds a grant), so an agent can distinguish it 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.

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

Usage is implied rather than stated: the scoping sentence tells the agent this is the narrow, single-company revocation, which is a real selection cue. But no sibling is named and there is no explicit when/when-not framing (e.g. 'use beel_delete_member to remove the member from the account entirely').

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real value beyond them: post-deletion reads return 404 and existing invoice lines are preserved because lines copy data rather than reference the product. That tells the agent what is and is not destroyed, which is the key risk question for a delete.

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

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

Three short sentences, front-loaded with the action and its immediate effect, followed by the side-effect caveat; nothing is padded. The trailing endpoint/URL metadata is reference material rather than instruction, which is a minor use of space.

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

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

For a two-parameter destructive tool with no output schema, the description covers the effect, the read consequence, and the historical-data consequence, which is what an agent needs before invoking it. It leaves unaddressed whether other artifacts (recurring invoice templates, series defaults) referencing the product are affected, and it does not flag irreversibility explicitly.

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

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

Schema description coverage is 100%, and the company_id description already explains tenant scoping and the 403 behavior in detail. The description text itself adds no parameter-level meaning, so the baseline of 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource plus the scope ('from the catalog of this company'), so an agent knows exactly what is removed. It does not name the close sibling beel_delete_products_bulk or explain how it differs, so it stops short of full sibling differentiation.

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

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

Usage is implied by the description of the effect (product gone, 404 afterwards), but there is no explicit when-to-use/when-not-to-use guidance and no mention of the bulk deletion alternative for multiple products. The agent must infer the right moment to call it.

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

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

Beyond the destructive/idempotent annotations, it discloses the key behavioral trait: the operation can partially succeed, with `deleted_products`, per-product `errors` keyed by `product_id`, and counts in `summary`. It even explains why the endpoint returns 200 with a body instead of 204, which 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.

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

Front-loaded with the action and the batch limit, then a short bullet explaining the partial-result semantics. The trailing endpoint URL and docs reference are mildly redundant with the tool name but still useful for traceability.

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

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

There is no output schema, and the description compensates by naming the return fields and their meaning. Combined with the destructive annotations and full schema coverage, an agent has everything needed to call it and interpret the result correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured data. The description restates the 100-ID cap on `ids` but adds no new syntax or edge-case meaning for `company_id`, so the baseline of 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource+scope: deletes the products listed in `ids` from the catalog of this company. It is clearly distinguishable from the single-item sibling beel_delete_product and from beel_delete_customers_bulk by naming the exact resource and endpoint (DELETE /v1/companies/{company_id}/products/bulk).

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

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

It gives concrete batching guidance — 'up to 100 IDs per request; send several requests for more' — which tells the agent when to loop versus when one call suffices. It stops short of explicitly routing single-product deletions to beel_delete_product, so the alternative-selection guidance is implied rather than stated.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description does not need to re-establish danger. It still adds real behavioral detail beyond them: permanence, cancellation of pending scheduled generations, and the explicit non-effect on already-issued invoices — the exact points an agent needs before committing an irreversible action.

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

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

The primary effect and its blast radius are front-loaded in two tight sentences, followed by endpoint reference and a guardrails pointer. The endpoint line and warning bullet are boilerplate but small and clearly separated; nothing is padded.

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

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

For a two-parameter destructive tool with no output schema, the description covers what is destroyed, what survives, and where to look for fiscal guidance. It does not state whether the response returns confirmation data or how the template's history records are retained, but the essentials for safe invocation are present.

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

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

Schema description coverage is 100%, and the two UUID parameters already document their semantics including the 403/404 disclosure behavior. The description adds nothing about parameter format or cross-company scoping, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

"Permanently deletes a recurring invoice template" names a specific verb and resource, and the follow-up sentence separates its scope from sibling mutations like beel_delete_invoice and beel_set_recurring_invoice_status by stating that generated invoices are untouched and pending generations are canceled.

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

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

The description implies usage through the effect statement (pending generations canceled, existing invoices preserved), which lets an agent judge consequences. However, it never names alternatives such as pausing via beel_set_recurring_invoice_status or skipping a cycle via beel_skip_recurring_invoice, which are the natural non-destructive routes an agent would want to consider first.

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

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

Goes well beyond the annotations: it discloses that the code is not released and recreating it yields 409 SERIES_CODE_DUPLICATED, that the delete cascades from deactivation, and the two distinct end states for a default series. These are non-obvious consequences an agent could not infer from destructiveHint/idempotentHint alone.

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

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

Front-loads the core action, then uses bolded labels for the two edge cases, keeping each point scannable and non-redundant. The endpoint and read-before-calling block are useful rather than filler, though the guardrail pointers make the definition slightly longer than strictly necessary.

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

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

For a two-parameter destructive mutation with no output schema, the definition covers the soft-delete semantics, the error codes an agent will encounter, and the prerequisite ordering for default series. Nothing material needed to invoke it safely is missing.

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

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

Schema coverage is 100% and both parameters already carry detailed descriptions, including the company_id scoping and 403 behavior. The description adds only an indirect reference to series_id in the context of SERIES_DEFAULT_NOT_FOUND, so the schema continues to do the heavy lifting.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Soft-deletes an invoice series') plus the state transition it performs ('deactivating it first if it is active'). This is clearly distinguishable from siblings like beel_patch_series or beel_set_default_series without opening any schema.

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

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

Gives explicit preconditions for the tricky case: a default series cannot be deleted while another active series of the same document type exists, and must be 'promote[d] ... first'. It also points to beel_rules_list and the beel://guardrails resources before calling. It stops short of naming the concrete sibling tool to use for promotion (beel_set_default_series), so the routing is implied 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.

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still earns credit for spelling out what is actually destroyed — the subscription itself and all future event delivery — plus the reversible alternative. It stops short of saying whether delivery history or logs survive the deletion, which is the one behavior an agent might still wonder about.

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

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

Three short sentences, front-loaded with the destructive consequence, then the reversible alternative, then the API reference. Every sentence carries distinct information and nothing is repeated from the annotations or schema.

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

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

For a two-parameter destructive tool with full annotation coverage and no output schema, the description supplies everything needed to call it correctly: the effect, the irreversibility, the alternative, and the endpoint. The only unaddressed detail is post-deletion retention of delivery records, which is not essential to invoking the call.

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

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

Schema description coverage is 100% and both parameters are richly documented in the schema, including the 403/404 disclosure semantics for cross-account access. The description adds only the endpoint template, which maps the parameters to path segments but adds no meaning beyond what the schema already states, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Permanently deletes a webhook subscription") and immediately states the operational consequence ("No further events are delivered to its URL"). It also distinguishes itself from the reversible path by naming the `active` = `false` alternative, so an agent can tell it apart from `beel_patch_webhook_subscription` without opening either schema.

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

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

It gives an explicit when-not-to-use rule: to stop deliveries reversibly, set `active` to `false` instead. That is a direct routing instruction to the sibling patch tool, and the endpoint line confirms the underlying resource path.

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

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

Beyond the annotations (destructive=true, idempotent=true), the description discloses that this is a soft delete with the row preserved in the audit trail, that the operation cascades to every eligible event sharing the payment identity or source object, that all affected rows share a single transaction and one `deleted_at` timestamp, that ineligible and unprocessed RECEIVED events are left untouched, and that the response returns the named event. That is substantial behavioral detail an agent could not infer from the hints alone.

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

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

It is front-loaded with the action and reversibility before the dense scope rules, and every clause carries operational meaning; nothing is filler. The middle paragraph is heavy with nested parentheticals, which slows parsing on a first read, but the complexity being described justifies the length.

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

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

For a destructive, cascading mutation with no output schema, the description covers what is affected, what is preserved, transactional behavior, failure conditions, and what the response contains. An agent has everything needed to call it correctly and to anticipate the blast radius.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `event_id` is not merely the row removed — it is a selector whose payment identity or source object determines the full scope of the cascading discard. That reinterprets the most consequential parameter in a way the schema text does not.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ('Removes a payment event from the default list (soft delete)') and immediately clarifies that it is reversible, which separates it from an ordinary delete. It also points at the restore counterpart, so an agent can distinguish it from beel_restore_payment_event and beel_resolve_payment_event 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.

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

The description gives clear context for when the operation applies (removing events from the default list while retaining audit trail) and names the restore path for reversal, plus explicit conditions under which it fails: events linked to an issued invoice or currently processing return 400. It does not explicitly compare against other sibling event tools such as beel_resolve_payment_event or beel_retry_payment_event, which keeps it 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.

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

Annotations only declare destructive/idempotent/not-readOnly. The description goes well beyond that: which credentials are deleted, that auto-invoicing stops immediately, that later charges are silently ignored, and crucially that already-issued invoices are untouched. It also discloses the non-obvious limitation that the provider-side OAuth grant survives, which an agent could otherwise wrongly assume.

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

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

Front-loaded verb and scope, then two tight bullets covering effect and the provider-side caveat, then the endpoint reference. Every sentence carries information an agent needs; nothing is redundant with the schema.

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

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

For a destructive, two-parameter mutation with no output schema, the description covers the safety-relevant consequences, the permission boundary, what is and is not affected, and the underlying endpoint. Nothing needed to invoke it correctly or explain the outcome to a user is missing.

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

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

Schema description coverage is 100%, with both UUIDs documented in detail (including 403/404 disclosure behavior and the note that a provider slug alone does not identify a connection). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Disconnects the payment connection named by {connection_id}') and adds the ownership scope ('a company that your account owns or manages'). This distinguishes it from siblings like beel_update_payment_connection and beel_list_payment_connections without requiring the reader to open their schemas.

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

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

Gives clear context for when to use it: to delete stored credentials and halt auto-invoicing. It also redirects the agent for the adjacent need (revoking provider-side authorization) to the provider's own dashboard, which is a genuine alternative path. It does not explicitly say when to prefer update_payment_connection over this deletion, so it falls short of a full when/when-not statement.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is met. The description adds real behavioral context beyond them: a long page without section returns its introduction plus its sections, and it explicitly labels returned text as documentation content rather than instructions, which guards against prompt injection from retrieved docs.

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

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

Three sentences, front-loaded with what the tool does before the parameter mechanics. The middle sentence is dense with layered clauses but each carries information; nothing is purely redundant with the title.

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

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

No output schema exists, and the description partially compensates by saying the result is Markdown and that an unsectioned long page returns introduction plus sections. What is missing is the shape of the response when a section is requested or what happens with an unresolvable page, but for a read-only docs retriever the definition is largely sufficient.

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

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

Schema description coverage is 100%, so page, url, section and sections are already documented in detail, including example anchors and the 10-item cap. The description restates those accepted forms (md_url, url, path, title) without adding syntax or edge-case behavior the schema lacks, so baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Read one page of the BeeL documentation ... as Markdown', plus the section-level variant. It is distinguishable from beel_docs_search and beel_docs_list by its single-page read scope and by referencing a search result's md_url as input.

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

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

It gives concrete selection guidance: pass page from a search result, use section to read only part, use sections to read several parts of the same page in one call. It stops short of explicitly saying to call beel_docs_search first when the page is unknown, so the workflow with siblings is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral context: the payload is documentation text and must be treated as untrusted content, not instructions — a prompt-injection guard the annotations cannot provide. It stops short of noting pagination or result-size expectations for a potentially large listing.

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

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

Three short sentences with zero filler: scope first, alternative second, safety caveat last. Each sentence carries distinct information an agent needs before calling.

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

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

For a no-parameter read tool with no output schema, the description tells the agent what it returns (pages plus URLs), when to prefer it, and how to treat the content. The only real gap is volume or pagination expectations given that it lists "every" page.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies an unfiltered full enumeration with no arguments, which matches the empty schema and leaves no ambiguity about how results might be narrowed.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("List every documentation page with its URL"), which is immediately distinguishable from beel_docs_get (single page) and beel_docs_search (query-based). An agent knows exactly what it gets back — URLs, not page bodies.

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

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

It gives an explicit selection rule: use this "only to browse," and it names the sibling tool beel_docs_search as the faster choice for targeted lookup. That is the exact when-to-use / when-to-use-something-else guidance the schema cannot express.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the return shape — matching pages with a snippet plus page and section identifiers — and the prompt-injection warning that returned text is content, not instructions. That warning is meaningful operational guidance beyond the structured fields. It does not discuss result volume or ranking behavior.

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

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

Two sentences, front-loaded with the action and scope, then the routing guidance, then the safety caveat. No restated title, no filler, and every clause carries distinct information.

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

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

For a read-only three-parameter search with no output schema, the description supplies return shape, the natural follow-up tool, and an injection caveat. Nothing an agent needs in order to call it or interpret results is missing.

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

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

Schema coverage is 100%, so area, limit and query are already fully documented, including the English/Spanish examples and the enum-like area values. The description only gestures at content categories (error codes, fiscal rules), which duplicates the schema. Baseline 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search the BeeL documentation") and enumerates the indexed content types — guides, API reference, error codes, fiscal rules. It also distinguishes itself from the sibling it is most likely to be confused with by naming beel_docs_get as the follow-up reader.

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

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

"Use it for how the API, a field or a flow works; then read that section with beel_docs_get" gives a clear when-to-use condition plus the explicit alternative and next step. It stops short of an exclusion clause — it never says when to prefer beel_docs_list, beel_rules_list or beel_schema_get, which overlap in subject matter.

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

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses the short 5-minute URL lifetime, the copy-selection rule (generated document until a signed copy is submitted, then the signed one), and the failure mode with status code 400. That is meaningful operational context; only the exact response payload shape is left unstated.

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

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

The return value and URL lifetime are front-loaded in one sentence, followed by two short labeled bullets for state and failure behavior, plus a one-line endpoint reference. Every element earns its place with no redundancy.

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

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

There is no output schema, so the description must carry the return-value burden; it does so by naming the presigned URL and its validity window, and it covers the main error path. It stops short of describing the exact response field names, which a caller must inspect at runtime.

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

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

Schema description coverage is 100% and the single company_id parameter already carries a rich description covering UUID format, 403 behavior, and the fact that account context is derived from the ID rather than the BeeL-Active-Company header. The description adds nothing further about the parameter, so the baseline 3 applies.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a precise verb and resource — returns a 5-minute presigned URL to download the company's representation PDF — which is clearly distinct from the other representation tools (get, generate, cancel) and from beel_get_invoice_pdf. It does not explicitly name a sibling to route against, so a 4 rather than a 5.

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

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

It implies when the tool is usable by describing the two document states (unsigned vs. signed submitted) and the 400 when nothing has been generated, which effectively hints that beel_generate_representation must run first. However, it never states when to prefer this over beel_get_representation or another PDF endpoint, so guidance is inferential.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the real blast radius: the holder keeps the account, NIFs and invoices, nothing is deleted or anonymised, and billing impact starts next cycle. It also discloses the reversibility mechanism and consent requirement after claiming, which annotations cannot express.

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

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

Front-loaded summary sentence followed by three tight bullets (holder, reversibility, entitlement) and the endpoint pointer. Every line carries operational value with no restatement of the tool name.

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

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

For a destructive, one-parameter mutation without an output schema, the description covers outcome, data preservation, billing effect, reversibility conditions, required entitlement and the underlying endpoint. Nothing an agent needs before invoking it is missing.

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

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

Single parameter with 100% schema description coverage; the schema already explains that a non-managed account answers identically to a nonexistent one. The description adds no parameter detail, which is acceptable here since the schema carries the full burden and the tool takes only one path-bearing identifier.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Ends the management relationship over an account you provisioned") plus the consequence (loss of access, NIFs stop being billable). It is clearly distinguishable from siblings like beel_provision_account, beel_change_managed_access_level and beel_cancel_representation.

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

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

It states the applicability condition (accounts you provisioned), the reversibility window (only while unclaimed) and the entitlement required (`manage_accounts`). It does not explicitly route the agent to a less drastic sibling such as beel_change_managed_access_level when the goal is only to reduce access, so it falls short of a full when/when-not/alternative statement.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description's repetition note reinforces rather than originates that fact. It goes genuinely beyond the annotations by spelling out the three per-document-type outcomes (kept unchanged, created with code F/S/R and format {CODIGO}-{YYYY}-{NUM:4}, or omitted with no default when the code is taken) — the last case is a non-obvious partial-failure mode an agent must be able to report. Missing are permission/auth expectations and whether the creation 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.

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

Front-loaded with the action and outcome, then three tight bullets for the branching cases, then a short note on the fixed-size response, then the endpoint. Nearly every sentence earns its place. The 'Closed catalogue' paragraph is slightly over-explained for a single-parameter, non-paginated call, but it does preempt a pagination question.

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

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

With no output schema, the description correctly compensates by describing the return set: one entry per DocumentType, no pagination, whole set in every response, and the case where a document type is absent from the response. That is the information an agent needs to interpret results. What is not covered is what the returned entries look like beyond code/format, and any permission requirements for the PUT.

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

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

There is only one parameter and its schema description already covers 100% of the semantics, including the 403 behaviour and the header-independence detail. The description contributes the useful framing that the request takes no body and that the desired end state is one default per document type, but adds nothing company_id-specific. Baseline 3 applies when the schema does the heavy lifting.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb and resource: ensure a default invoice series exists for STANDARD, SIMPLIFIED and CORRECTIVE, and return the resulting set. The scope is unambiguous. It does not, however, distinguish itself from the similarly named siblings beel_set_default_series and beel_get_default_series, so an agent still has to infer which of the three is the right call.

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

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

Usage context is implied rather than stated: the 'desired end state' framing and the 'repeating it changes nothing' note suggest when this is preferred over a blind create. But the description never names beel_set_default_series as the alternative for pinning a specific series, nor beel_get_default_series for read-only inspection, leaving the most important routing decision to inference. The 'Read before calling' pointers to beel_rules_list and the guardrails resources are useful prerequisites, but they are references, not selection guidance.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false and destructiveHint=false, and the description goes well beyond them: it spells out that the document is not issued, not numbered against the series and not emailed, and it maps failure modes to status codes (400 for an already-invoiced event, 422 for a document rejected by invoicing rules, with no draft created). That is exactly the mutation-safety context an agent needs before calling a create-style tool.

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

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

The purpose is front-loaded in the opening sentence and the three bullets each earn their place by covering draft status, eligibility and rejection handling. The trailing endpoint/reference line is useful for traceability. Slightly long overall, but no sentence is filler.

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

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

There is no output schema, yet the description covers what matters for the caller: what is produced (an un-issued, un-numbered draft), what is not produced (no email send), and what errors to expect. Combined with annotations that already carry the idempotency and safety profile, 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.

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

Schema coverage is 100%, so all four parameters — including the subtle idempotency-key collapsing behavior — are already documented in the schema, and the description adds little per-parameter meaning. The one phrase it does add, 'under the NIF in the path', is actually in tension with the schema's note that company_id is the identifier and 'not its NIF', which sows mild confusion rather than resolving it. Baseline 3 fits: the schema carries the parameter burden.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ('builds a draft invoice') and scopes the input precisely to 'a payment event that could not be invoiced automatically', which separates it from beel_create_invoice, beel_issue_invoice and beel_retry_payment_event. It also states what the automatic flow would have applied (recipient resolution, tax treatment), so the agent knows this is a replay of existing rules rather than a fresh manual invoice.

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

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

It gives an explicit eligibility gate ('only those that produced no invoice can produce a draft') and an explicit follow-up alternative ('Issue it yourself once it is right'), which points the agent at beel_issue_invoice for the next step. What it does not do is name the recovery siblings it should be preferred over — beel_retry_payment_event, beel_resolve_payment_event, beel_discard_payment_event — so the routing decision among those is left to inference.

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

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

Annotations already flag destructive and idempotent behavior, but the description adds substantial context beyond them: it is a "fiscal act" that consumes numbering from the template's series, may issue and send the invoice, advances `next_generation` by one period, and returns `null` when the template becomes `COMPLETED` past its `end_date`. It further explains `draft_in_advance` timing: if the pending period's scheduled date is today or earlier the invoice is issued immediately, otherwise a review draft is created for the scheduled date.

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

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

The first sentence states the action immediately, and the bullet structure front-loads the most important behavioral distinction: it brings the upcoming occurrence forward rather than adding one. The description is long but each bullet carries operational meaning, including the response field, draft timing, and the explicit non-use case for extra invoices. The guardrails pointer at the end is useful without dominating the text.

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

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

For a destructive fiscal mutation without an output schema, the description covers the critical consequences: numbering consumption, issuance and sending, occurrence consumption, `next_generation` advancement, and the `null` completed-state response. It also handles the `draft_in_advance` edge case and clearly routes the extra-invoice scenario elsewhere. An agent has enough context to call this correctly and understand the side effects.

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

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

Schema description coverage is 100% and the schema already documents `company_id`, `recurring_invoice_id`, and `idempotency_key` in detail, including error behavior and idempotency-key tradeoffs. The description does not add parameter-specific meaning beyond that schema documentation. A baseline 3 is appropriate because the schema carries the parameter semantics.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: it "runs the generation of this recurring template immediately, out of its schedule." It explicitly distinguishes the operation from skipping and letting the schedule run by explaining that all three consume exactly one occurrence. It also clearly excludes using this endpoint for an extra invoice outside the calendar, naming normal invoice creation and derivation as alternatives.

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

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

Usage is explicitly bounded: "do not use this endpoint" for an extra invoice outside the calendar, with alternatives named (`POST /v1/companies/{company_id}/invoices/derivations` or a normal invoice). It also explains how manual generation relates to skipping and scheduled generation, so an agent knows when this tool is the right choice versus siblings like beel_skip_recurring_invoice and beel_create_recurring_invoice_derivation.

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