BeeL MCP server

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

Annotations already include idempotentHint, but the description adds substantial behavior beyond them: mode is never inferred from the credential environment, PROD may return 402 with a checkout_url, 403 is returned for non-billing-owners, repeated calls return already_active and no second charge, and pending switch-offs are cancelled without charging. This is rich, non-redundant transparency.

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 organized under clear headings — modes/billing and idempotency — with the core purpose in the first sentence. Bullet points keep the billing and safety semantics digestible, and each sentence contributes unique operational knowledge 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 state-changing activation with billing and idempotency complexity and no output schema, the description covers the important outcomes: immediate vs checkout-required activation, error conditions, repeated-call behavior, and pending switch-off cancellation. An agent has enough to decide if this tool fits and to anticipate the main responses.

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 descriptions already cover company_id, idempotency_key, and the body fields well (67% coverage). The description supplements this by explaining that the environment/mode is always explicit and never taken from credentials, and by tying success_url/cancel_url to the checkout flow. It adds meaningful context without repeating 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 names the specific operation — 'Switches an existing company on' — with the body-carried mode and the actor/scope called out. It is clearly distinct from siblings like beel_deactivate_company and beel_delete_company because the object ('company') and action ('activate on') are explicit.

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 to call this tool: to activate a company in TEST or PROD, with concrete consequences for each mode. It does not explicitly name sibling alternatives or say 'use X instead', so it stops short of a 5, but the conditions around billing, checkout, and ownership are strong usage 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?

The description adds substantial behavioral detail beyond the annotations: it explains the production impact, what remains unaffected, the 400 rejection when no active representation exists, and frames cancellation as a state transition rather than a delete-if-present operation. This is valuable context that annotations alone do not provide.

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

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

The description is compact and efficiently structured: a single introductory sentence, two high-signal bullets, and the endpoint. No filler or redundant repetition of schema 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?

The description covers the operation's effect, error condition, and scope. With no output schema, a brief note on the successful response would be ideal, but the description is still sufficient for correct invocation given the rich schema and annotations.

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 is thoroughly documented in the schema itself. The tool description adds no additional parameter-level semantics, 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 uses a specific verb—'Cancels'—with a precise resource: 'the active AEAT representation of a company.' This clearly distinguishes it from siblings like beel_generate_representation, beel_get_representation, and beel_download_representation_document.

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 effect bullet clarifies when this tool is appropriate: when the company must stop submitting invoices to AEAT, while explicitly noting that activation and non-VeriFactu invoice issuance are untouched. It does not name alternatives explicitly, but the context is clear and no exclusions are needed.

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 supply a safety profile (not read-only, not destructive, not idempotent, open world); the description adds substantive behavior beyond that: claim-state gating of raises, the manage_accounts entitlement, the fiscal-representation prerequisite for OPERATE, and the fact that billing is unaffected by level. It does not describe failure modes or whether lowering is reversible, so it stops short of a full behavioral picture.

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?

Bulleted, front-loaded with the action, and the endpoint is placed at the end as a locator. Slightly redundant: the billing fact appears both in the description and again inside the AccessLevel enum description, and the OPERATE/representation note is duplicated in the same way.

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 mutation with no output schema and only safety annotations, the description covers the conditions, entitlements, and side-effect semantics an agent must know. It omits what a successful response contains and what error surfaces on an unmanaged or claimed account, but those gaps are 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?

The access_level enum is fully documented in $defs and account_id carries a useful schema note about non-disclosure of managed accounts. The description nonetheless adds real meaning beyond the schema by tying OPERATE to the fiscal-representation requirement and by clarifying that level never affects billing. With 50% schema coverage this compensates adequately, though it says nothing further about the account_id argument itself.

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 (Updates) and resource (the access_level you keep over an account you provisioned), plus the concrete endpoint PATCH /v1/accounts/{account_id}/access-level. It is clearly distinguishable from provisioning/management siblings like beel_provision_account, beel_end_management, or the member-grant tools, since it is scoped to the provisioner's own access over a managed account.

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 when/when-not conditions: raising is only possible while the account is unclaimed, and after the holder takes ownership only they can raise it. It also names the entitlement needed (`manage_accounts`) and the extra prerequisite for OPERATE (signed fiscal representation), which is exactly the routing information an agent needs before calling.

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: atomicity of the `issue` call with rollback semantics, the terminal CONVERTED status, the specific 400/409/422 error codes and their meanings, and the guarantee that a second call never creates a second invoice. This meaningfully enriches the destructiveHint/idempotentHint annotations rather than restating them.

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 purpose, then uses scannable bolded bullets for conversion scope, preservation, the `issue` flag, and errors, closing with the endpoint and a guardrails pointer. Slightly long but nearly every line carries distinct information; structure is strong.

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, destructive mutation with no output schema, the description covers lifecycle transitions, atomicity, idempotency consequences, and the full error taxonomy, and it routes the agent to the state-machine guardrail resource. Nothing essential to calling it correctly 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 75%, and the description deepens the `issue` parameter with failure semantics (issuing failure leaves nothing created, proforma stays ACTIVE, SERIES_NUMBER_COLLISION path) that the schema's one-line description does not. company_id and invoice_id semantics live in the schema; the description adds linkage context via source_proforma_id.

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+resource ('Converts an accepted proforma ... into a real invoice') and immediately distinguishes itself from generic invoice creation by naming the source object and the resulting STANDARD draft linked via source_proforma_id. An agent can tell it apart from create_invoice, issue_invoice, or create_invoice_derivation 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?

Gives clear preconditions for use (only ACTIVE proformas convert, EXPIRED-but-ACTIVE still converts) and points to the guardrails resource for the lifecycle. It does not, however, explicitly name sibling alternatives or say when NOT to reach for this tool versus e.g. create_invoice, so it stops short of full routing 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?

Adds rich behavior beyond the annotations: 30-day lifetime, only the last token live, and that re-issuing invalidates the prior token so the old link dies. It also discloses the `manage_accounts` entitlement requirement. Annotations already establish idempotentHint=true and readOnlyHint=false, so the added context — particularly token invalidation and auth needs — is genuinely valuable, though return shape is left implicit.

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 constraints (email, lifetime, not-an-invitation, entitlement) and the endpoint. Every bullet earns its place; nothing is redundant boilerplate.

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 mutation tool with no output schema, the description covers purpose, mutation semantics, token lifecycle, auth requirement, and the alternative flow. The only gap is the undocumented `language` parameter, which is minor given the schema carries it.

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 reinforces the `email` semantics (required when holderless, mismatch rejection). However, it never mentions the `language` parameter at all, leaving that field to the schema. Baseline 3 fits since the description adds partial value but does not fully compensate for the uncovered parameter.

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 single-use claim_token and claim_url) plus the downstream effect (holder sets a password and takes ownership). It also explicitly distinguishes itself from the invitation flow, naming the sibling tool beel_create_invitation's underlying endpoint, so an agent can separate the two 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?

Gives explicit when/when-not rules: send `email` when the account has no holder, omit the body to re-issue for the existing holder, and use the invitations endpoint instead when adding a second person. The mismatch-rejection rule (a differing email is rejected, not a replacement) is stated outright.

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, idempotentHint=true, destructiveHint=false, but the description goes further: 403 when not billing subject, 402 for accounts without billing, 409 duplicates with company_id in error.details, 422 POSTAL_CODE_INVALID_ES, and no checkout is opened. That is rich behavioral context beyond the annotations.

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

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

Front-loaded with the core action, then tight labelled bullets (activate, numbering, Billing, Duplicates, Addresses). It is on the long side and the numbering bullet partly repeats what the schema already says about NUMBERING_REQUIRES_ACTIVATION, but each section carries information useful at call time.

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 creation endpoint with no output schema, the description covers the mutation's side effects, error codes, account-resolution auth model, and defers numbering/NIF domain rules to explicitly named guardrail resources. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 67%, and the description meaningfully supplements it by explaining the activate/numbering relationship and its failure mode (NUMBERING_REQUIRES_ACTIVATION), which the schema states more minimally. It does not restate address or tax field semantics, but those are well covered in the schema itself.

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 company under the account the request resolves to') and immediately clarifies the NIF registration scope. It also explicitly distinguishes the create act from activation, naming beel_activate_company's endpoint as the separate door for switching an existing company on.

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 when to use each behavior: activate defaults true, activate:false defers switching-on to the activations endpoint, numbering is only accepted when activation happens, and it routes the agent to three guardrail resources before calling. Conditions and alternatives are all named.

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 write/destructive/idempotent/open-world, and the description goes far beyond: the original's status becomes VOIDED or RECTIFIED, the original's PDF is untouched, a zero-total corrective is issued as PAID with payment_date = issue_date, the corrective never inherits the original's series, and a 4-year deadline plus number-collision behavior are disclosed. This is unusually rich behavioral disclosure for a mutation tool.

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

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

The bulleted layout is front-loaded and scannable, but the text is very long and duplicates prose already carried by schema properties — the IRPF/surcharge inheritance rules, the recipient data-correction flow and the series behavior are restated nearly verbatim in the $defs. For an agent with a context budget, that overlap is waste even though each individual bullet is coherent.

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 a four-parameter body hiding deeply nested fiscal enums, the description carries the whole behavioral burden and does so: error conditions, deadlines, inheritance rules, series handling and the AEAT-rejection prerequisite are all present. An agent has everything needed to call this correctly without consulting external resources, which are additionally pointed to.

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 still adds material meaning: rectification_type drives whether lines are required or forbidden, series_id defaults to a corrective series that may be auto-created, circumstance_date is restricted to R1/R2/R3/R5 and bounded by the operation date, and recipient is only for data corrections under R4 with no lines. None of that is inferable from the schema alone.

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 states a specific verb and resource ('Issues a corrective invoice that amends the invoice in the path') and immediately distinguishes the artifact from an edit ('a new fiscal document with its own number, not an edit of the original'). An agent can separate this from beel_create_invoice, beel_void_invoice and beel_create_invoice_derivation 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 explicitly routes between TOTAL and PARTIAL, states what each does to the original's status, and names exclusions and alternatives — e.g. a withholding-only PARTIAL is rejected and the guidance is to void the invoice and issue a new one, and an erroneous corrective is fixed by rectifying the original rather than the corrective. When-not-to-use cases are enumerated with the exact 422 codes.

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 and idempotentHint=true, so the safety profile is covered. The description adds genuine value by explaining that a retry switching from the deprecated flat route replays instead of duplicating, but says nothing about failure modes, permissions or the 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 with the core purpose, then the idempotency bullet, endpoint and a warning. No wasted sentences, though the guardrail line is a pointer rather than actionable content and reads slightly cryptically.

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 annotations covering safety and idempotency, and no output schema, the description is mostly sufficient. It is missing sibling routing guidance and only vaguely references the NIF/census guardrail resource, which an agent may not know how to use.

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 itself documents all three parameters in depth (company_id, idempotency_key, body). The description only glosses the idempotency_key at a high level, adding little beyond what the schema already states.

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 new customer under this company') with the POST endpoint. It does not differentiate from close siblings like beel_create_customers_bulk or beel_patch_customer, so an agent gets the purpose but no routing signal.

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 description flags a 'Read before calling' guardrail and explains the idempotency-key nuance, but never says when to prefer this over bulk creation or when to update an existing customer 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?

The description goes well beyond the annotations by detailing atomicity (nothing persisted on validation failure, 422 BULK_VALIDATION_ERROR), the exact behavior of dry_run (validate vs. create, 200 vs. 201), and that both modes return the same per-record report. It also points to a NIF-validation guardrail resource, adding valuable 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 bullet points to organize atomicity, dry_run, and report details. Every sentence is informative and earns its place; the warning block is a concise pointer for deeper validation rules.

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?

Given the complexity of a bulk atomic write, the absence of an output schema, and the rich annotations already covering idempotency and safety, the description is complete enough. It covers the critical behaviors (atomicity, dry_run, status codes, error code) an agent needs to call it 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?

With schema description coverage at 75%, the baseline is 3, but the description adds meaning beyond the schema for dry_run by listing what gets validated (tax identifiers against AEAT, duplicates, field formats) which is not in the schema's dry_run description. It does not elaborate on company_id or the body structure, so it doesn't fully compensate for the remaining 25% 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?

The first sentence states a specific verb, resource, and scope: 'Creates up to 500 customers of this company in a single call.' This clearly distinguishes it from the single-customer sibling tool and other bulk siblings. The endpoint line reinforces the operation.

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 provides clear context for when to use dry_run and explains the atomicity, but it does not explicitly name alternatives like beel_create_customer or state when not to use this tool. Usage is strongly implied by the bulk scope and the detailed dry_run 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?

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false, openWorld=true). It discloses that the token is returned once and never readable again, that invitation_url is a ready-to-use link, that an explicit null grants is rejected with 422, that grants are only meaningful for MEMBER, and that send_email defaults to false so the caller must deliver the link. This is exactly the extra behavioral context an agent needs for a mutation tool.

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

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

Front-loads the one-line purpose and then uses tight, scannable bullets for each parameter concern. Well-structured, though a few lines (notably the grants null/[] rule) restate the schema almost verbatim, which is minor waste against an otherwise efficient layout.

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 compensates by explaining the returned token and invitation_url. For a mutation tool it covers role constraints, grant rules, and email behavior adequately, though it never mentions the idempotency_key parameter or the practical consequence of the idempotentHint.

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 earns its place by adding semantics: what grants means for each role, the omit-vs-[]-vs-null distinction, and the default/effect of send_email. Some of this is duplicated verbatim from the schema, but the role-conditional explanation of grants adds genuine meaning beyond the structured fields.

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 single-use invitation for a person to join the account with the given account_role.' An agent can immediately tell this is the invite-creation tool, distinct from siblings like beel_list_invitations, beel_get_invitation, and beel_delete_invitation. It does not, however, explicitly name an alternative or contrast itself with a sibling, keeping it short of a 5.

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

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

Usage is implied rather than stated: the agent can infer this is the tool for inviting a person, but there is no explicit 'use this when...' guidance, no mention of prerequisites such as needing account-admin rights, and no routing away from alternatives like beel_create_claim_token. Constraints ('OWNER cannot be invited') are given but they govern parameter values, not 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 only cover readOnly/idempotent/openWorld/destructive. The description adds substantial behavior beyond them: AEAT submission is asynchronous so a 2xx means 'accepted for submission', not registered, and submission_status returns PENDING; a number collision fails with 400 SERIES_NUMBER_COLLISION without consuming a number; PROFORMA is non-fiscal, born ACTIVE, ignores issue_directly. This is exactly the kind of non-obvious behavior an agent needs.

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 well-organized bullets for Issuing / Document type / Related, and a labeled 'Read before calling' block. It is long, but the bullet structure makes it scannable and the resource pointers earn their place as routing aids rather than 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 complex fiscal-create operation with no output schema, it covers the create/issue decision, the asynchronous submission caveat, a concrete failure mode, the PROFORMA exception, the related derivation route, and explicit pointers to the guardrail resources that hold the remaining fiscal detail. Nothing essential for a correct call 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 75% schema coverage and a very detailed schema, the baseline is 3, but the description adds real meaning: it explains what options.issue_directly does to numbering/issuing, the PENDING return semantics, and the effect of `type` (PROFORMA being non-fiscal, born ACTIVE, ignoring issue_directly). It leaves the remaining parameters (company_id, wait_for_pdf, idempotency_key) 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?

States a specific verb+resource ('Creates an invoice for this company') and immediately scopes it (issuer from the company in the path, draft unless requested otherwise). It actively distinguishes itself from siblings by stating CORRECTIVE is not accepted here and by pointing to the derivation endpoint for copying.

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: issuing vs draft default, PROFORMA behavior, and explicitly routes copying to POST …/invoices/derivations. It also routes deeper rules to guardrail resources. It stops short of naming other near siblings (batch creation, simplified exchange, recurring invoices), so it 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?

The description significantly exceeds the annotations by disclosing non-atomicity, irreversibility of issuance, the 50-invoice cap, and the per-invoice result shape. It makes real side-effect behavior explicit despite idempotentHint/destructiveHint already present.

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-organized with a clear summary sentence followed by scannable bullets. Every bullet adds distinct information, and there is no filler or repetition of schema 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?

For a mutating batch operation without an output schema, the description conveys the essential behaviors: non-atomicity, result reporting, limit, and operation modes. It does not spell out the exact response payload or error codes, but the per-invoice reporting statement and richer schema descriptions fill most operational gaps.

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 only lightly touches parameter semantics (operations, new_status, invoice_ids limit); the schema itself carries detailed descriptions for body, company_id, and idempotency_key. With 67% schema coverage and strong schema prose, the description neither needs nor adds much parameter-level 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?

Opens with a specific verb ('applies one operation') and resource ('set of invoices'), names the two operations (ISSUE/STATUS), and states per-invoice success/failure reporting. It also explicitly carves out sibling concerns (PDFs, email, exports), so an agent can distinguish it from nearby tools.

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 when-not guidance and names the alternative endpoints/sub-resources for downloading PDFs, sending email, and exporting. The operation semantics (ISSUE vs STATUS, new_status requirement) also clarify when each mode should be selected.

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 non-read-only, idempotent, non-destructive and open-world, so the bar is lower; the description adds genuinely new behavior in the partial-failure contract ('invoices whose PDF cannot be attached are reported in `failures`, and the message is still sent with the rest') plus the 'no address is inferred from any profile' rule. It does not discuss rate limits or the external-send consequences implied by openWorldHint=true.

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 three tight bullets that each carry a distinct constraint (required recipients, the 200 cap, failure semantics). The trailing endpoint line is slightly redundant given the tool name but costs little.

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 documenting the `failures` field of the result, which an agent needs to interpret a partial send. Still missing: whether the call is synchronous, what identifies the created delivery for later retrieval, and any permission prerequisites beyond the 403 note that lives in the 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 a moderate 67%, and the description largely restates what the schema already encodes (recipients minItems=1, invoice_ids maxItems=200) rather than adding meaning. The optional parameters (cc, subject, message, language, idempotency_key) — including cc's subtle quota/default behavior — are left 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 first sentence gives a precise verb and resource ('Sends one email carrying the PDFs of several invoices ... as attachments'), and the plural scope implicitly contrasts with the single-invoice beel_send_invoice sibling. It stops short of explicitly naming that sibling or any other alternative, so differentiation is inferred rather than stated.

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 constraints ('up to 200 invoices per message'), which tells the agent this is the bulk-delivery path, but there is no explicit when-to-use/when-not statement and no mention of beel_send_invoice for single-invoice delivery or of beel_list_email_deliveries for follow-up.

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 safety profile (not read-only, idempotent, non-destructive). The description adds substantial behavioral detail beyond that: the source is left untouched, exactly which fields are copied versus reset (number, status, dates, VeriFactu data, PDF), that a CORRECTIVE copy is born STANDARD, and the concrete 422 SERIES_INCOMPATIBLE_DOC_TYPE failure mode.

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 and the key invariant (source unmodified), then bulleted detail on mode and series, then a clearly marked 'read before calling' block. Each section earns its place, though the guardrails pointer adds some 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 mutation tool with no output schema, the description covers side effects, copied/reset fields, series validation, and an explicit error code, and routes the agent to lifecycle resources. It stops short of describing the returned draft's shape, but the resource pointers compensate adequately.

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 documents mode, series_id, from_invoice_id and notes. The description still adds real meaning: series_id is validated against the copy's type (which may differ from the source's), the source's series is the fallback, and the mode's only legal value is DUPLICATE. It goes beyond restating 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+resource ('Creates a draft invoice derived from an existing invoice of this company') and immediately disambiguates the operation from a plain create by noting the source is not modified. It is distinguishable from siblings like beel_create_invoice and beel_convert_proforma_to_invoice 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?

Explains the single mode (DUPLICATE) and what it copies versus resets, plus points the agent at beel_rules_list and the invoice-state-machine resource for the fiscal rules and lifecycle. It does not explicitly say when to prefer this over beel_create_invoice or beel_convert_proforma_to_invoice in prose, but the context is clear.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, openWorld. The description adds genuinely useful behavior beyond that: duplicate `code` yields 409 PRODUCT_DUPLICATE and an incoherent tax pair yields 422, with the default active/category behavior spelled out.

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 tight bullets for Required/code/Taxes/several-at-once, ending with the endpoint. Every line carries an actionable constraint 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?

No output schema, but the description states what is returned (the product with its id) and documents the notable failure modes. Combined with a 67%-covered schema, an agent has enough to invoke correctly; minor detail like the full parameter list is left to the 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 already rich, but the description adds value the schema does not: the uniqueness semantics of `code` within the company and the specific error it triggers, plus the coherence requirement between equivalence_surcharge_rate and main_tax.regime_key.

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 company's catalog) plus the return value (the product with its id). It also distinguishes itself from the bulk sibling by naming beel_create_products_bulk for multi-create.

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 context: only `name` is required, omitted `category` defaults to SERVICE, the product is created active, and it routes bulk creation to the /products/bulk endpoint. It lacks an explicit 'when not to use this / use X instead' for single-vs-list cases, but the practical guidance is clear.

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 by disclosing partial-success semantics (each row validated and reported independently, with rejected rows returned in the report while the rest are created), and the counterintuitive status contract: 201 even when nothing was created, 422 only for malformed requests with nothing processed. Annotations cover idempotency and safety only, so this adds real behavioral knowledge.

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 single-sentence purpose, then two tight bullets on partial operation and status codes, then the endpoint. Bold labels make it scannable; the only slight excess is that the status-code bullet is long for one concept.

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 should say something about the response, and it does name the per-row report and the status contract. It leaves the report's actual structure and any auth/permission expectations unstated, but for a bulk-create tool the batch-level semantics are well covered and the heavy tax/regime validation rules live in the nested 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 description coverage is 67% and the description adds essentially no parameter meaning: it restates the 100-item cap already encoded as maxItems and says nothing about company_id, the body shape, or idempotency_key (the latter is only covered in the schema). It does not compensate for the parameters the schema leaves thin.

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 up to 100 products in the catalog of this company') plus the batch cap, which distinguishes it in practice from the single-product beel_create_product. It never names the sibling or explicitly contrasts the two, so differentiation is inferred from the name rather than stated.

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 explains batch mechanics but gives no when-to-use guidance: nothing tells the agent when to prefer this over beel_create_product, what prerequisites (e.g. company state, permissions) apply, or when not to call it. The only routing signal is the implicit 'bulk' in the name.

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 safety profile (readOnly=false, idempotent=true, destructive=false); the description adds substantial behavior the agent could not otherwise infer — the first occurrence is found month-by-month regardless of cadence, a past start_date is stored but never anchors generation backwards, missed periods are not generated, the review-draft window is fixed at 5 days, and VeriFactu registration is decided at issue time rather than carried by the template. It also flags preview_days as superseded.

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 the first sentence, then bold-labelled bullets (Cadence, cadence-governs-step, start_date, draft_in_advance, VeriFactu) make it scannable. It is longer than strictly necessary and some cadence explanation duplicates the schema, but no bullet 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 creation tool with no output schema and no annotation contradiction, the description covers the scheduling semantics an agent must understand before calling. It omits what the call returns (the created template object and its next_generation) and gives no guidance on the required series_id or optional customer_id, leaving those entirely to the 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 the description adds real interpretive value for the parameters that matter most: how frequency interacts with the first invoice, how day_of_month behaves, and what start_date in the past does to next_generation. It largely synthesizes rather than repeats the schema text, though there is some overlap with the equally detailed field descriptions.

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 precise verb and resource — 'Creates a recurring invoice template under this company' — and enumerates what the template holds (lines, recipient, series, payment) plus the recurrence driving it. It is immediately distinguishable from a one-off invoice creation. However, it never names or contrasts with the closest siblings (beel_create_recurring_invoice_derivation, beel_generate_recurring_invoice_now, beel_create_invoice), so it falls 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 purpose and by the 'Read before calling' pointer to beel_rules_list for fiscal rules, but there is no explicit when-to-use/when-not-to-use statement and no named alternative. The one genuine routing hint (use a scheduled invoice instead of max_invoices below 2) lives inside the schema, not the description.

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 disclose idempotency and open-world behavior, while the description adds meaningful context: the source invoice is not modified, the recurrence cadence is not inherited from the source, and VeriFactu registration follows the company's regime when each invoice is issued. It does not describe return values or rate limits, but these are less critical for a creation 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 description is front-loaded with the core purpose, then structured into focused bullets for the source invoice, recurrence, and VeriFactu. Every sentence earns its place, and the warning at the end is directly actionable.

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 multi-parameter creation tool with rich annotations and a detailed input schema, the description covers all invocation-critical details: required recurrence fields, source-invoice constraints, cadence semantics, and the VeriFactu caveat. No output schema exists, and the description does not need to explain return values 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?

The description adds meaning beyond the schema for `from_invoice_id` (must belong to the company; unreachable invoices are reported like nonexistent ones) and for recurrence parameters (which are required vs optional, and that cadence is not copied from the source invoice). With 67% schema description coverage, the description still provides useful contextual semantics, though some details duplicate 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 first sentence states a specific verb and resource: 'Creates a recurring invoice template of this company taking its lines, recipient, series and payment data from an existing invoice.' This distinguishes the tool from the sibling `beel_create_recurring_invoice`, which creates a template from scratch, by making the existing-invoice derivation central.

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 to use it: when you already have an invoice and only want to describe the recurrence. It also includes a prerequisite warning to read fiscal rules before calling, but it does not explicitly name the alternative tool (`beel_create_recurring_invoice`) or provide when-not-to-use exclusions.

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 behavior well beyond the annotations: specific 409/422 error codes (SERIES_FORMAT_OVERLAPS, SERIES_UNASSIGNED_TYPE_NOT_ALLOWED, SERIES_FORMAT_NUMBER_TOO_LONG), cross-series overlap detection with proforma exemption, and the non-obvious side effect that the first series of a type is auto-promoted to default even when default_series:false is sent. These are exactly the mutation side effects an agent needs.

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 structured bullets that each carry a distinct constraint or error code; nothing is filler and each sentence earns its place. It is long, but the length is justified by the density of real rules rather than repetition.

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 description covers creation rules, failure modes, side effects, and resource pointers thoroughly. It does not describe the success response shape beyond the default_series flag, but the error and side-effect coverage is strong enough to call it 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 67%, and the description reinforces the highest-risk params with behavioral meaning: document_type rejection rule, code uniqueness, format {NUM}/{NUM:X} requirement, counter_reset default interaction with year tokens, and the default_series auto-promotion rule. It adds context beyond the schema for the critical fields, though name/active/description/initial_number are left 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?

States a precise verb+resource+scope: 'Creates an invoice series under a company,' plus the exact endpoint POST /v1/companies/{company_id}/series. An agent can distinguish this from sibling write tools like beel_set_default_series or beel_ensure_default_series immediately.

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 pre-call context (read beel_rules_list with a domain, or the beel://guardrails resources) and enumerates concrete rejection conditions that shape whether the call should proceed. It stops short of routing to alternatives such as patch_series or list_series, so it is clear context without explicit when-not/alternative 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?

Goes well beyond the annotations: it discloses that the source invoices become VOIDED with cause EXCHANGED (records preserved), that the exchange invoice cannot be voided afterwards, the exact 422 error codes for each failure mode, and the VeriFactu F3 gating behavior. This is rich side-effect disclosure that the readOnlyHint=false/destructiveHint=false/idempotentHint=true annotations alone do not convey.

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

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

Long but well front-loaded: the core purpose is in the first sentence, followed by scannable bolded bullets for what it issues, source-invoice handling, voidability, and VeriFactu. Each block earns its place, though the prose is dense enough that a tighter version is imaginable.

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 naming the response-relevant fields (replaced_invoice_ids, F3/AEAT registration, verifactu state) and pointing to guardrail resources for pre-flight checks. An agent has enough to call it correctly, though return-shape detail remains 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 67%, and the description adds real meaning on top: it explains that simplified_invoice_ids must be issued, non-voided, non-exchanged, non-corrected invoices whose lines carry over in order, and clarifies the recipient/series defaults. It does not, however, explain the options/idempotency_key fields, leaving some schema work uncovered.

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+resource ('Issues a full invoice in exchange for one or more simplified invoices already issued') and explicitly distinguishes itself from the sibling concept 'It is not a corrective invoice'. An agent can tell exactly what this produces and what it does not.

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 a clear triggering scenario ('when the customer asks for an invoice with their details') and rules out the nearest alternative (corrective invoice), plus preconditions for the source invoices. It stops short of naming sibling tools like beel_create_corrective_invoice or beel_create_invoice as explicit alternatives, so it is clear context without full 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?

Annotations only supply the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true). The description adds the critical one-time-return behavior of `secret`, the BeeL-Signature signing header, the best-effort and possibly-null `test_delivery`, and the hard subscription cap with its error code — none of which the annotations 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 purpose sentence is front-loaded, and the bolded bullet headers (secret, test_delivery, account_relationship, Limits) let an agent skim to the detail it needs. Despite its length, every line carries operational information an agent cannot get from structured fields.

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 carries the return-value burden and does so: it explains the one-time secret, the test-delivery result (including the null case), and the relationship field. Creation constraints, error codes, and duplicate-delivery consequences are all covered, so nothing needed to call this 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%, above the low-coverage threshold, and the description's account_relationship gloss ('own', 'managed', or 'all') largely restates the enum description already in the schema, as does its reference to the `events` list. It adds little syntax or format meaning for `url`, `account_id`, or `idempotency_key` beyond what the schema documents.

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 ('Registers an HTTPS endpoint to receive notifications') and scopes it to the event types in `events`, which cleanly separates it from beel_patch_webhook_subscription, beel_get_webhook_subscription, and beel_test_webhook_subscription. The trailing endpoint line (POST /v1/accounts/{account_id}/webhooks) confirms the operation unambiguously.

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 concrete usage context: the limit of 10 active subscriptions, the 400 WEBHOOK_ACTIVE_SUBSCRIPTION_LIMIT_REACHED rejection, and the consequence of registering the same URL twice. It never names an alternative tool or an explicit 'do not use this when' condition (e.g. to modify an existing subscription, use patch), so routing 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?

Beyond the annotations, the description discloses important non-obvious behavior: Live switch-off is scheduled with effective_at, nothing is refunded, TEST/PROD are immediate, repeats return already_scheduled or a silent no-op, and Live requires billing-subject permission. This is exactly the side-effect detail an agent needs.

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 well-structured with a direct lead sentence followed by scannable, headed bullets. Each section covers a distinct behavioral aspect—sealing, timing, repeats, permissions—without redundancy or 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?

Even without an output schema, the description names the key response signals (effective_at, already_scheduled), explains the no-op case, details timing per environment, and states permissions. An agent receives enough information to invoke the tool correctly and anticipate the outcome.

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 already well documented in the input schema. The description reinforces the environment semantics and adds Live-specific permission context, but it does not add substantial new parameter-level meaning beyond 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 description opens with a specific action and resource: 'Switches the company off in the mode given by environment; the other mode is untouched.' It also draws a clear line against deletion ('Sealed, not deleted'), which distinguishes it from both beel_activate_company and beel_delete_company.

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 provides clear usage context, including mode-specific scheduling, repeated-call behavior, and the Live permission requirement. It does not explicitly name an alternative tool or state a when-not-to-use condition, but the mode-scoped semantics are strong enough for an agent to infer appropriate use.

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 annotations: it names the exact blocking error codes (409 COMPANY_ACTIVE_IN_PRODUCTION, 409 COMPANY_HAS_INVOICES, 400 CANNOT_DELETE_PRIMARY), states that existing invoices are retained but unresolvable once the NIF is gone, and warns that omitting Idempotency-Key turns a retry into a 403 instead of 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?

Front-loads the effect, then uses labeled bullets for blockers, deactivation timing, test behavior, and idempotency. Dense but every bullet carries decision-relevant information; only the trailing guardrail pointer feels somewhat tacked on.

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 call with no output schema, the description supplies effect, blockers, error codes, idempotency semantics, and the endpoint. Nothing needed to call 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 description coverage is 100% and the company_id description already covers UUID format, ownership derivation, and 403 non-disclosure. The prose adds no parameter-level meaning beyond the schema, 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 ('Removes a company from the account') plus the observable effect ('stops appearing and stops being billed'). It is clearly distinguishable from siblings like beel_deactivate_company and beel_delete_member.

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 selection context: it explains that deactivation in Live is scheduled to end-of-cycle and that removal only becomes possible afterwards, and that Test NIFs are removed immediately. It never explicitly frames deactivate vs delete as a choice, but the prerequisite chain is 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 mark this as destructive and idempotent. The description adds valuable context beyond those: future invoices omit the logo, already issued documents are unchanged, and deleting an absent logo still returns 204. This gives the agent a clear model of side effects and idempotent 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?

Three tight sentences with no filler. The core action is first, followed by consequential effects and the idempotent edge case, then the endpoint for completeness. 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?

Given a single required parameter, no output schema, and annotations covering safety traits, the description is fully adequate. It explains the main effect, the persistence effect, the idempotent outcome, and the exact HTTP endpoint. There is nothing an agent needs to invoke it correctly that 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?

The input schema has 100% description coverage, including a detailed explanation of company_id, the derived account context, and the 403 behavior. The description adds no parameter-level meaning beyond echoing the endpoint, which is acceptable because the schema already carries the load. 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: 'Removes the logo of a company.' It clearly identifies the target (company logo) and distinguishes it from the many other delete_* siblings like delete_company or delete_customer. The endpoint string reinforces the exact operation.

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 when to use this tool: when the goal is to remove a company logo. It does not explicitly mention when not to use it or name alternative tools, but given the highly specific resource and the sibling list, an agent can infer the correct context. More explicit exclusion guidance would raise this score.

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, but the description goes well beyond them: it explains that deletion is a soft delete retained for tax records, that the record returns 404 and is excluded from every `active` filter, that the NIF is released for reuse, and it documents the 409 CLIENT_HAS_INVOICES and 400 REFERENCED_BY_RECURRING_INVOICE error codes.

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?

Bold-labeled bullets make the consequences front-loaded and scannable, and each bullet carries distinct information (soft-delete behavior, identifier release, two error paths, the patch alternative). Slightly long, 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?

For a destructive delete with no output schema, the description supplies everything an agent needs: exact semantics, downstream visibility effects, identifier reuse, and the full set of failure modes with status codes.

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 path parameters are fully documented in the schema (including the company_id context/disclosure semantics). The description adds only the endpoint path shape, not new meaning for the parameters themselves, 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 (Deletes), resource (a customer of this company) and a scope constraint (that has no invoices) that immediately separates it from siblings like beel_delete_customers_bulk and beel_delete_member. The endpoint line reinforces the exact operation.

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 when-not condition (customers with invoices cannot be deleted) and supplies the alternative action (update with `active` set to `false`). It also flags a second blocking case, recurring-invoice recipients, so the agent knows exactly when to pick a different 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?

Even though annotations already include destructiveHint and idempotentHint, the description adds substantial behavior: partial operation, 200 instead of 204, 200 even when nothing is deleted, HAS_INVOICES status, internal retention for tax purposes, identifier release, and invoice copy semantics. This goes well beyond the structured hints and gives an accurate model of side effects.

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

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

The length is justified by the destructive partial-operation semantics, and the content is organized with bold headers and a front-loaded one-sentence summary. Every included detail addresses a behavioral fact an agent needs, with no filler. The endpoint line at the end is minor redundancy but does not detract.

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 bulk operation with no output schema, the description covers the key facts: partial success, HTTP status behavior, invoice-holding failure reason, the semantic effect on identifiers, and the distinction from deactivation. The only omitted details, such as exact response body fields, are unlikely to prevent correct invocation and are not promised elsewhere.

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 the schema already fully documents both parameters and the baseline is 3. The description does not add parameter-level semantics beyond the schema's comma-separated ids and company_id context. Its additional detail is operational rather than parameter-focused.

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,' which captures the bulk scope. It also contrasts with the singular DELETE endpoint and with PATCH deactivation, so an agent can distinguish it from beel_delete_customer and beel_patch_customer. The name and description align cleanly.

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 'Deleting is not deactivating' section provides an explicit alternative (PATCH with active:false) and explains the consequences of each choice, which is real routing guidance. It also states that the bulk operation has the same semantics as the singular DELETE endpoint, implying the bulk-vs-single distinction. However, it never explicitly says 'use beel_delete_customer for a single customer,' so the when-not-to-use guidance is slightly incomplete.

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), the description discloses the real side effect (acceptance link stops working), the retention behavior (history is not removed), and the non-disclosing 404 error semantics. It omits auth/permission requirements, which is the main remaining gap.

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 in the first clause, uses tight bullets for the two edge cases, and ends with the endpoint. No sentence is redundant.

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 mutation with no output schema, the definition covers side effects, error behavior, and state prerequisites. It is nearly complete, lacking only explicit permission/auth context, though the account_id schema field partially compensates with its 403 note.

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 UUID parameters are already fully documented in the schema (including the 403/404 semantics). The description only restates the endpoint path and adds no parameter-specific 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 (revokes) and resource (a PENDING invitation) and clarifies the effect ('its acceptance link stops working'). The scope qualifier 'PENDING' distinguishes it from sibling read/list tools such as beel_list_invitations and beel_get_invitation without needing 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?

Explicitly defines when the tool succeeds (only PENDING) and when it fails (ACCEPTED/REVOKED/EXPIRED answer 404). It does not name a sibling alternative for handling already-resolved invitations, so it falls just short of a full when/when-not/alternatives treatment.

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/idempotent, but the description adds the crucial fact that the record is soft-deleted ('marked as deleted rather than removed') and preserves the fiscal trail, plus a non-obvious side effect: deleting a proforma-derived draft returns the proforma from CONVERTED to ACTIVE. That is behavioral context the 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 core action, then bulleted distinctions and the endpoint, then a short pre-call warning with resource pointers. It is longer than average, but each block (void-vs-delete, proforma lifecycle, guardrails reference) carries distinct information; minor trimming is possible.

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 2-parameter mutation with no output schema, the description covers the action, its reversibility model, the divergent sibling behavior, and where to find fiscal rules. Nothing an agent needs to call this 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 100% and the schema itself carries a rich company_id description (UUID, 403 behavior, header semantics), so the schema already does the work. The description adds no parameter-level syntax or format information beyond it, 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 ('Deletes a draft invoice of this company') and immediately scopes it to drafts, distinguishing it from sibling beel_void_invoice. An agent can tell it apart from the void/rectify tools 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 names when not to use it (issued invoices are never deleted, they are voided via POST .../{invoice_id}/void) and the case that selects it (drafts, including proforma-converted drafts). It also points the agent to beel_rules_list / guardrail resources for preconditions.

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, destructiveHint, and openWorldHint, so the bar is lower. The description still adds real value: the concrete `204` response on an unscheduled invoice and the `scheduled_invoices` feature caveat that separates it from the PUT. It does not describe confirmation requirements or rate limits, keeping it out of 5 territory.

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 sentences are front-loaded and tight, but the '⚠️ Read before calling' block is generic boilerplate and contains a sentence fragment ('The status names, the proforma lifecycle, and which tool performs each operation.') that lacks a verb and adds noise rather than routing 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 destructive, no-output-schema mutation, the description covers the resulting state, idempotency behavior, and the feature difference from the PUT, which is what an agent needs to call it safely. Minor gaps remain (auth/permission specifics), but the essentials 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 both parameters are well documented in the schema (company_id even explains 403 masking). The description adds nothing about the two parameters, 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?

States a specific verb and resource ('Removes the scheduling of an invoice') plus the resulting state ('returning it to a plain draft'), and explicitly distinguishes itself from the sibling PUT endpoint by noting it does not require the `scheduled_invoices` feature. An agent can tell this apart from beel_set_invoice_schedule 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?

Gives clear context: this unschedules while keeping the invoice as a draft, is safe to call on an already-unscheduled invoice, and has a lighter feature requirement than the PUT. It stops short of explicitly routing against other alternatives (e.g. beel_delete_invoice) or stating when deletion is preferred over unscheduling.

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 readOnlyHint=false, so the description is not burdened with restating that. It adds a valuable non-obvious behavioral rule: the account's last OWNER cannot be 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 description is two short sentences plus the endpoint line. It front-loads the core action and includes only the meaningful guardrail about the last OWNER, with no fluff.

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

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

For a simple two-parameter destructive action, the description plus annotations cover the safety profile and the key business rule. It could mention consequences to related grants or permissions, but nothing essential for invoking it correctly is omitted.

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 schema already documents both parameters well. The description adds no parameter-level meaning beyond the endpoint path, which is already represented in 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 description states a specific verb ('Removes') and resource ('a member's access to the account'), and reinforces it with the exact DELETE endpoint. This clearly distinguishes it from siblings like beel_delete_member_grant or beel_delete_invitation.

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?

No guidance is given about when to choose this tool over alternatives, nor about prerequisites beyond the last-OWNER restriction. The intended use is only implied by the verb and resource.

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 mark this as destructive, and the description complements that by specifying exactly what is destroyed: only the grant for one company, while other company grants are preserved. It adds meaningful scope context beyond the raw destructiveHint flag, though it does not discuss reversibility or error 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?

The description is compact and front-loaded with the key action and scope, followed by a useful endpoint reference. Every sentence contributes: the first defines behavior, the second clarifies non-destructive scope, and the third provides the HTTP mapping.

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

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

For a simple three-parameter destroy operation with complete schema descriptions and safety annotations, the definition is largely sufficient. The main gap is the absence of any response or error semantics beyond the 403 already noted in the account_id parameter, but this does not critically impair 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%, with each parameter already described in the schema. The description's endpoint template helpfully maps the parameter names to path segments, but it does not add substantive meaning beyond what the schema provides. 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 uses a specific verb and resource: 'Revokes a MEMBER's access to one company.' It clearly distinguishes this from deleting the member entirely by stating that grants over other companies are unaffected. The endpoint further reinforces the exact operation.

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 provides clear context: this tool revokes a member's grant for a single company only, leaving other grants intact. However, it does not explicitly name alternative tools like beel_put_member_grant or beel_delete_member, so it stops short of full when-to-use versus when-not-to-use guidance.

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

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

Annotations already flag destructive and idempotent, and the description adds the concrete post-conditions: the product disappears from listings, reads return 404, and existing invoice lines are preserved because lines copy data. That is exactly the side-effect information an agent needs before a destructive call.

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 plus the endpoint line, front-loaded with the verb and resource, then effect and side-effect. 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?

With destructive/idempotent annotations, a fully documented schema, and no output schema, the description covers the remaining gaps (listing removal, 404 semantics, invoice-line preservation) that an agent needs to call this safely.

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 company_id and product_id are fully documented in the schema itself. The description adds nothing about parameter format or behavior, 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 (deletes) and resource (a product from this company's catalog), which is unambiguous. It does not, however, name or distinguish itself from the sibling beel_delete_products_bulk, so an agent must infer single-vs-bulk from the 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?

Usage is implied by the singular 'a product' versus the bulk sibling, but the description never states when to pick this over beel_delete_products_bulk or notes prerequisites. Context is inferable but not 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 mark the operation as destructive and non-read-only, and the description adds meaningful behavioral detail: partial operation, per-item success/failure reporting through `deleted_products` and `errors`, `summary` counts, and why HTTP 200 with a body is returned instead of 204. This goes beyond annotations and helps the agent set expectations.

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?

Core action, batch limit, response semantics, and endpoint are presented in a compact, front-loaded structure. No filler or repetitive content; the bullet formatting improves scannability.

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?

Even though there is no output schema, the description explains the response shape and counts sufficiently, and the schema covers both parameters in detail. The main omission is explicit retry/idempotency behavior, but the idempotentHint annotation covers that. Overall an agent has what it needs to invoke the tool 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%, and the schema entries already explain the comma-separated `ids` format and the UUID `company_id` semantics, including the 403 behavior. The tool description itself does not add new parameter-level meaning beyond what the schema provides, 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?

States the operation explicitly: deleting products listed in `ids` from the company catalog, with a bulk limit. The 'up to 100 IDs' phrasing and endpoint underscore the batch nature, distinguishing it from single-product deletion siblings. This is specific and actionable.

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?

Describes the request size limit and instructs sending multiple requests beyond 100 IDs, which is practical usage guidance. However, it does not explicitly mention alternatives such as `beel_delete_product` for single deletions or contrast when bulk vs single should be chosen. The context is clear but exclusions are 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 already declare destructiveHint=true and idempotentHint=true, but the description goes further by specifying the exact destruction scope: pending scheduled generations are cancelled and already-generated invoices are not affected. It does not add auth, permission, or rate-limit context, though those are partly covered in the schema parameter descriptions.

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 purpose and effect, then the endpoint, then a clearly marked warning block. It is appropriately sized and well-structured, though the endpoint and rules pointer add minor vertical 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 tool with no output schema and fully described parameters, the description covers purpose, deletion scope, endpoint, and a guardrail pointer. It does not describe the response (e.g., no-content or deleted object), but an agent has enough context to invoke it 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 required parameters (company_id, recurring_invoice_id) are fully documented with UUID format and 403/404 behavior. The description adds no parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('Permanently deletes') and resource ('recurring invoice template of this company'), and immediately scopes the effect by clarifying that pending scheduled generations are cancelled while already-generated invoices are unaffected. This distinguishes it from sibling delete tools like beel_delete_invoice or beel_delete_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?

The description makes the tool's purpose clear but does not explicitly say when to choose it over alternatives such as pausing via beel_set_recurring_invoice_status or skipping an occurrence via beel_skip_recurring_invoice. The 'Read before calling' note points to fiscal rules but is a prerequisite pointer, not usage 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is clear. The description adds substantial behavior beyond annotations: soft-delete semantics, automatic deactivation, the fact that the code remains reserved (with the specific 409 SERIES_CODE_DUPLICATED consequence), default-series constraints, and the final SERIES_DEFAULT_NOT_FOUND error state when no series remains.

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 operation, then uses bullets to separate the two critical edge cases (code retention and default-series handling). Every sentence earns its place: the bullets describe non-obvious constraints and error responses, and the 'Read before calling' section points to relevant resources without bloating the main 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 mutation with full annotation coverage and no output schema, the description is complete: it states the operation, soft-delete behavior, ordering constraint (deactivate first), post-deletion consequences, error conditions, and relevant reference resources. No essential agent-facing detail 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%, and the schema itself already documents company_id in detail and series_id minimally. The description adds no new meaning for the two parameters beyond what the endpoint path already implies. Per the rubric, a 3 is the baseline 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 first sentence gives a specific verb (soft-deletes), the resource (invoice series), and a key behavioral qualifier (deactivating it first if active). This distinguishes the operation from a hard delete and from sibling tools like patch_series or set_default_series. The endpoint reinforces the resource and path semantics.

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 provides clear constraints and prerequisites for deletion, including the default-series rule and the consequence of deleting the last series. It implies that another series must be promoted first, but it does not name an explicit alternative tool (e.g., set_default_series) or state when to prefer deactivation over deletion. The 'Read before calling' pointers add useful context but are 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?

The description discloses the permanent, destructive effect ('No further events are delivered to its URL') and contrasts it with reversible deactivation. It goes beyond the `destructiveHint` annotation by specifying the behavioral consequence on event delivery. It does not mention auth requirements, but those are covered in the parameter schema descriptions, so the description adds meaningful context without contradiction.

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

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

The description is brief and front-loaded with the core purpose. It contains three short sentences: the action, the effect, and the reversible alternative, followed by the endpoint. Every sentence earns its place, with zero redundancy or 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 delete operation without an output schema, the description covers the essential behavioral aspects: permanent deletion, effect on deliveries, and the reversible alternative. It doesn't describe the response, but that's often trivial for deletes and not required. The schema handles parameter ownership and error semantics, so nothing critical is missing for an agent to call this 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 coverage is 100% – both `account_id` and `webhook_id` have detailed descriptions in the input schema covering semantics, ownership, and error responses. The tool description itself adds no parameter-specific guidance beyond referencing the endpoint, which is already implied by the schema. With full coverage, a baseline 3 is appropriate; the description doesn't need to compensate.

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 the action precisely: 'Permanently deletes a webhook subscription.' It names the specific resource and the irreversible nature, and distinguishes itself from the reversible alternative (set `active` to `false`). It also provides the HTTP endpoint, which reinforces the operation.

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 explicitly tells when to use this tool and when not to: 'To stop deliveries reversibly, set `active` to `false` instead.' This points to an alternative (likely `patch_webhook_subscription`) and clarifies the irreversible context, giving the agent clear decision 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?

Adds substantial context beyond the annotations: soft-delete semantics, audit-trail retention, single-transaction application with a shared deleted_at, untouched RECEIVED-state events, and the 400 condition for invoice-linked or in-processing events. This also explains why destructiveHint=false and idempotentHint=true hold, rather than contradicting them.

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

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

Front-loads the essential fact (soft delete, restorable) and the endpoint, then elaborates scope. The middle scope paragraph is dense and slightly repetitive about RECEIVED-state events, but nearly every sentence carries distinct behavioral 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?

Covers everything an agent needs for a mutation with no output schema: scope of effect, eligibility failure mode, idempotency behavior, and what the response returns ('carries the event named in the request'). Nothing material 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%, so the baseline is 3, but the prose adds real meaning: it clarifies that event_id drives a cascading scope over sibling events sharing a payment or source object, which the schema's one-line 'identifier of the payment event' does not convey.

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 ('Removes a payment event from the default list (soft delete)') and immediately distinguishes it from siblings by naming the restore operation and the audit-trail persistence. An agent can tell this apart from beel_restore_payment_event, beel_retry_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?

Explains the scope model in detail (whole payment when external_payment_id matches, source object grouping, otherwise the single event) and the alternative path back via restore. It does not explicitly say when NOT to use it beyond the eligibility/400 rule, but the operational context is clear.

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/idempotent/openWorld, but the description adds substantial context beyond them: stored credentials are deleted, auto-invoicing halts immediately, subsequent charges are ignored, and already-issued invoices are unaffected. It also discloses the non-obvious limitation that provider-side authorization is NOT revoked, with a concrete remediation path.

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 scope in sentence one, then bulleted effect and caveat, then the endpoint. Every sentence carries distinct information 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 the action, prerequisites, side effects, non-effects, and the important caveat about provider-side authorization. Nothing an agent needs to invoke it correctly is missing.

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

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 both UUIDs thoroughly, including 403/404 disclosure semantics. The description only names connection_id in prose and adds no format or lookup detail beyond the schema, 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 (disconnects) and resource (payment connection) plus the required scope (a company your account owns or manages). An agent can distinguish it from beel_update_payment_connection, beel_initiate_payment_connection and beel_list_payment_connections 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 clear preconditions (account must own or manage the company) and decision-relevant consequences (auto-invoicing stops, future charges ignored). It also explains the follow-up needed to revoke provider-side authorization. It does not explicitly name sibling tools or say when to prefer this over updating or listing connections, so it stops 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 already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine unannotated behavior: a sectionless long page yields its introduction plus its sections, and it warns the returned text is documentation content rather than instructions to follow (prompt-injection guard).

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, no filler, front-loaded with the core action before parameter mechanics and edge-case behavior. 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?

With no output schema, the description still conveys return semantics (Markdown, intro-plus-sections default) and the partial-read options, which is everything needed to call this read tool 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 coverage is 100% and the schema already documents page, url, section, and sections in detail. The description restates the accepted forms (md_url/url/path/title) and the multi-section-in-one-call nuance, adding only marginal value beyond 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?

States a specific verb (read) and resource (one documentation page or some of its sections), plus the output format (Markdown). It implicitly distinguishes itself from the search/list siblings by noting the page argument can come from a beel_docs_search result.

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?

Clear context: it explains passing page, using section for a single part, sections for several parts of one page, and what happens for a long page without a section. It does not explicitly state when-not or name alternatives like beel_docs_list, but the search-result workflow is 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: the returned text is documentation content, not instructions to follow, which warns the agent about prompt-injection-style content.

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 purpose followed by routing guidance and a safety note. Zero redundancy; 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?

With no output schema, the description does the work of explaining what comes back (URLs plus documentation content). It is nearly complete, though it could note rough size or pagination behavior for a full-list 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?

The tool takes no parameters, so the schema carries nothing to document; per the baseline this scores 4. The description appropriately focuses on output (URLs, content) rather than inventing parameter guidance.

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 (list) and resource (documentation pages) and includes what each entry contains (URL). It also names the sibling beel_docs_search, so the agent can distinguish this browse tool from the search tool 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 scopes usage: use only to browse, and route to beel_docs_search when the goal is to find something. It gives both the when and the when-not with the named alternative.

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?

With readOnlyHint and openWorldHint already declared, the description adds real value: it discloses the payload contents (snippet, page, section) and, importantly, warns that returned text is documentation content rather than instructions to follow. That injection guard is genuinely useful behavioral context for an agent consuming untrusted doc text.

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 scope, followed by the routing hint and the safety caveat. 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, and the description compensates by stating what comes back (matching pages with snippet, page and section). Combined with the annotations and full schema coverage, an agent has everything needed to call and interpret this 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 100%, so query, area and limit are already fully documented, including the English/Spanish and example guidance. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (search) and resource (BeeL documentation), enumerates the covered corpora (guides, API reference, error codes, fiscal rules), and describes the return shape (matching pages with snippet plus page/section pointers). It is clearly separable from beel_docs_get (fetch a section) and beel_docs_list.

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 trigger ("how the API, a field or a flow works") and names the follow-up alternative beel_docs_get with the condition for reading the matched section. It does not contrast with the adjacent beel_docs_list, beel_rules_list or beel_schema_get, so a little routing ambiguity remains among the doc-family 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?

The description adds valuable behavioral context beyond the annotations: the presigned URL is valid for 5 minutes, the served copy depends on whether a signed copy has been submitted, and ungenerated documents are rejected. Nothing contradicts the read-only, idempotent, non-destructive 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 opens with the core return value, uses a short bullet list for nuanced behavior, and closes with the endpoint. Every line contributes useful information 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?

Given a single parameter, rich parameter schema, and no output schema, the description covers the return type, URL validity, state-dependent behavior, and the key error case. An agent has enough to call the tool correctly and interpret the common failure mode.

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 description already explains UUID semantics, that it is not a NIF, that the header plays no part, and the 403 behavior. The tool description adds no parameter-level detail and does not need to, since the schema already carries that weight.

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 clearly states the action ('Returns a presigned URL... to download the representation PDF') and the resource, with a precise endpoint. It differentiates through 'presigned URL' but does not explicitly contrast with siblings like beel_get_representation or beel_generate_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 provides clear operational context, such as which copy is served and the 400 error when the document is not generated, so an agent understands when the call is valid. However, it does not name alternatives or state when to prefer a different sibling tool, leaving route selection mostly 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?

Goes well beyond the annotations by disclosing what is lost, what the holder retains, that nothing is deleted or anonymised, and the precise reversibility boundary (only while unclaimed, only by the ending manager). This is exactly the kind of mutation context annotations alone 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 verb phrase followed by tight, labeled bullets (holder, reversible, entitlement) plus the endpoint. Every line carries information an agent needs; 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?

With no output schema, the description supplies the outcome semantics an agent needs: access loss, billing effect timing, and third-party impact on the holder. Nothing material 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% and the account_id description already documents format, ownership requirement, and the non-disclosure behavior for unmanaged accounts. The description adds no syntax or format detail beyond the schema, 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?

States a specific verb+resource+scope: 'Ends the management relationship over an account you provisioned,' which is immediately distinguishable from siblings like beel_provision_account and beel_change_managed_access_level. The endpoint line pins the operation further.

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 context for acting (you lose access, NIFs stop counting, you must hold manage_accounts) and explains the holder-side consequences. It does not, however, name an explicit alternative such as beel_change_managed_access_level for agents wanting to downgrade rather than end the relationship.

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 by enumerating the three outcomes: already-present (returned unchanged), missing (created with code F/S/R and format {CODIGO}-{YYYY}-{NUM:4}), and code-taken (type silently omitted and left with no default). That last partial-failure case is exactly the kind of behavior annotations cannot convey, and the closed-catalogue/no-pagination note closes the loop.

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 purpose and organized into labeled bullets that each carry distinct information. It is somewhat long, and the 'Closed catalogue' paragraph could be tightened, but no sentence 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 endpoint with no output schema, the description fully covers the response contract (the resulting set, with omissions named), the safety profile (idempotent, non-destructive), and the relevant domain references. An agent has everything needed to call it 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 description coverage is 100% and the single company_id parameter is documented exhaustively in the schema (UUID, header independence, 403 behavior). The description adds nothing about parameters, so the baseline 3 for fully-covered schemas 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 ('ensures') plus the exact resources (default invoice series for STANDARD, SIMPLIFIED, CORRECTIVE) and return behavior. It is clearly differentiated from a plain read like get_default_series, but it never names the near-siblings (beel_set_default_series, beel_create_series), leaving that distinction to be inferred.

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?

Explains the calling context well: no request body, an ensure/idempotent semantic where repeating changes nothing, and it routes the agent to beel_rules_list and beel://guardrails resources before calling. It lacks an explicit when-not-to-use or a direct pointer to set_default_series as the alternative, so it stops 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 already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is largely covered. The description adds genuine behavioral context beyond that: the draft is not issued, not numbered against the series and not emailed, and it discloses the 400 and 422 failure conditions. It does not restate the idempotency semantics, which live in the schema.

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

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

Front-loads the action in one sentence, then three tight bullets covering the draft-only constraint and both error paths, ending with the endpoint. Every sentence carries information; 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 mutating, open-world tool with no output schema, the description covers eligibility, side-effect boundaries and error behavior well. It stops short of indicating what the draft response contains or how to locate the created draft afterward, which would be the remaining useful detail.

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 parameter descriptions are unusually rich, so the baseline is 3. The description adds little parameter meaning; its phrase 'under the NIF in the path' is mildly at odds with the path, which actually carries company_id (the schema explicitly says it is the identifier, not the NIF), so it slightly muddies rather than clarifies.

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 ('Builds a draft invoice from a payment event') and scopes it precisely to events that could not be invoiced automatically, which distinguishes it from the automatic flow and from sibling payment-event operations like retry/resolve/restore. An agent can identify the action 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?

Gives a clear selection condition — only events that produced no invoice are eligible, otherwise 400 — plus the follow-up guidance 'Issue it yourself once it is right'. It does not, however, explicitly name alternatives (e.g. beel_retry_payment_event, beel_resolve_payment_event, beel_issue_invoice) that an agent might weigh against 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?

Annotations declare destructiveHint and idempotentHint, and the description adds substantial non-redundant behavior: the call is a fiscal act that consumes numbering from the template's series, issues and sends the invoice when the template is configured to, advances next_generation one period, and may flip status to COMPLETED past end_date. This is context an agent cannot get from the annotations alone.

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

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

Front-loaded with the core action, then bolded, scannable bullets that each carry distinct information (occurrence economics, response semantics, the do-not-use case, endpoint path, fiscal-rules pointer). No filler sentences.

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, no-output-schema fiscal mutation, the description supplies everything needed: the fiscal/numbering consequence, the occurrence accounting, the return field (next_generation incl. null case), the mis-use case, and a pointer to beel_rules_list/guardrails. Nothing material 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%, so company_id, recurring_invoice_id, and idempotency_key are already fully documented in the schema. The description references next_generation but that is a response field, not a parameter, so it adds no parameter-level semantics beyond the schema. 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 precise verb+resource+scope: it runs the recurring template's generation immediately, out of schedule, and explicitly frames it as consuming the pending occurrence ('brings the upcoming occurrence forward, it does not add one'). This distinguishes it cleanly from siblings like beel_skip_recurring_invoice, beel_create_recurring_invoice_derivation, and beel_create_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 explicit when-to-use (bring the pending occurrence forward now) and a strong when-NOT: 'An extra invoice outside the calendar: do not use this endpoint,' routing the agent to create a normal invoice or a derivation via POST .../invoices/derivations. It also clarifies how manual generation, skipping, and the schedule interact so the agent understands the alternative paths.

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: the prerequisite of a complete fiscal identity, the 400 failure mode, and rejection when an active representation already exists. It also clarifies that the generated document is unsigned, which is not evident from the annotations alone. No contradiction with annotations.

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

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

The lead sentence states the core purpose, followed by three focused bullets covering next steps, prerequisites, and failure conditions. There is no filler, and the most important scoping information is 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 mutating operation with no output schema, the description covers prerequisites, error behavior, and the downstream actions needed to complete the flow. The only notable gap is the exact response shape of the POST call, though the next-step guidance makes the intended usage clear.

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 parameter descriptions are already rich: company_id explains UUID vs NIF, account derivation, and 403 behavior, and idempotency_key explains collision behavior. The description adds no parameter-level information beyond what the schema provides.

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 ('Generates'), a specific artifact ('unsigned AEAT representation PDF'), and positions it as the first step of the representation flow. This distinguishes it from related siblings like beel_cancel_representation and beel_download_representation_document.

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 clearly frames when to use the tool: as the first step of the representation flow, with explicit next steps (download the PDF, sign it, submit it). It also states when not to call it: incomplete fiscal identity is rejected with 400, and an active existing representation must be canceled first. It does not name sibling tools directly, but the flow instructions are unambiguous.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the returned fields, which is useful since no output schema exists, but it does not disclose anything about error behavior, rate limits, or the non-disclosure semantics that live in the schema.

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

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

One dense sentence describing the return shape followed by the endpoint line, with the purpose front-loaded. It is efficient, though the mid-sentence field list makes the core noun phrase slightly harder to scan.

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-resource read tool with full annotation coverage and no output schema, the description compensates by enumerating the returned fields and naming the HTTP endpoint. Nothing critical is missing, though conditional fields (company_id only when one company) could be spelled out further.

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 account_id schema entry is notably rich (UUID, plus the non-existence non-disclosure rule). The description adds no parameter detail beyond the schema, 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?

States a specific verb and resource ('Returns one account you provisioned') and differentiates from the sibling beel_list_accounts by noting it returns a single account with the same shape as the list. The return fields (status, access_level, claim link state, company_id) further pin down what this tool is for.

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: fetch a single account when you have its account_id, and the mention of 'the same shape the list returns' gestures at beel_list_accounts. However, there is no explicit statement of when to use this versus the list endpoint, nor any prerequisites or exclusions.

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 read-only/idempotent safety profile, yet the description adds genuinely new behavior: absent fields mean 'nothing stored, not hidden', and a non-existent or unreachable company answers 403 so existence in another account is never disclosed. These are non-obvious semantics an agent could not infer 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?

Front-loaded with the return contract, then the PATCH-mirroring rationale, then the series exclusion, then the endpoint. Prose is a little long and the trailing 'Read before calling' bullet is vague pointer-only text, but every other 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?

With no output schema, the description carries the full burden of describing the return shape and does so thoroughly: identity, activation state, VeriFactu state, the complete set of PATCH-able fields, and the absence semantics. Nothing needed to call or interpret the response 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% and the single company_id parameter is already documented in depth (UUID, not NIF, 403 semantics, header plays no part) in the schema itself. The description adds no parameter-level detail 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+resource (returns the identity and activation state of a company) and enumerates the returned content (fiscal data, Test/Live switch state, VeriFactu registration). It also carves out what it does NOT return (invoice series, routed to GET /v1/companies/{id}/series), cleanly separating it from beel_list_companies and beel_get_series.

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 frames a key use case — reading back every field PATCH /v1/companies/{company_id} accepts so written values need not be cached — and names the alternative endpoint for series. It does not state when NOT to use it versus beel_list_companies or beel_get_setup_status, so it stops short of full when/when-not 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that it returns 'complete details' and gives the GET endpoint; it does not add error behavior, auth requirements, or response format beyond the schema's 403 note, but nothing contradicts 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?

One clear sentence plus the endpoint line; no filler. The core behavior is front-loaded and every word contributes.

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

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

For a simple read-only single-resource fetch with fully annotated params and safe-operation hints, the description plus endpoint is nearly sufficient. The only gap is the absence of any response structure, which matters since no output schema exists, but 'complete details' is adequate guidance for a customer object.

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%; company_id is exceptionally well explained and customer_id is minimally described. The description itself adds no parameter semantics, but the baseline of 3 applies because the schema carries the full 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 description uses the specific verb 'Retrieves' with the resource 'a customer of this company', and the endpoint line pins the exact operation. This clearly differentiates it from list/create/patch/delete customer 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?

The verb 'Retrieves' and the singular resource imply it should be used when complete details of one known customer are needed, but the description never explicitly contrasts it with alternatives such as beel_list_customers or states prerequisites.

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