inv.bg MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true; the description reinforces this with 'WRITE' and POST /clients. The dedupe warning adds real behavioral value by implying duplicates are not prevented server-side. It stops short of saying what a duplicate or validation failure returns.

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, mutation intent front-loaded, then prerequisite, then the alternative path. No filler and nothing buried.

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 ten-parameter mutation with no output schema, the description covers purpose, dedupe risk, and the nearest competing workflow. Still missing what comes back (client ID) and whether country/is_reg_vat have defaults that matter on creation.

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 70%, so the schema already carries most parameter meaning. The description names five fields (name, Bulstat, VAT, address, MOL) but adds no format or conditional logic beyond it, and says nothing about code, town, country, delivery_address, or is_reg_vat's coupling to vat_number.

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 ('add a company client') with a WRITE prefix and enumerates the key fields being supplied. It also draws the boundary against sibling tools: company clients here, individuals via invbg_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 an explicit prerequisite ('Check invbg_list_clients first to avoid a duplicate') and an explicit exclusion with the alternative to use instead ('For an individual (EGN) ... use invbg_create_invoice and is_to_person'). The when and the when-not are both 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 write, destructive and non-idempotent, and the description adds precisely the missing specifics: saved as DRAFT by default, draft=false consumes the next legal number and 'cannot be undone through this tool'. It also discloses a non-obvious side effect — that inv.bg may match an existing client by Bulstat/VAT and UPDATE that client with the passed details.

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 write/draft/irreversibility facts an agent needs first, then addressing rules, then VAT. Every sentence carries information, though the addressing sentence is a dense parenthetical chain that takes effort to parse.

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 27-parameter destructive tool with no output schema, the description covers draft-vs-issue, numbering, irreversibility and the client-creation side effect — the highest-risk behaviors. It never says what the call returns (invoice id/number), which matters for chaining into get_invoice or record_invoice_payment, and it is silent on duplicate/idempotency behavior.

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 96%, so the fields are already documented; the description adds the higher-order semantics the schema can't express well — the client_id vs to_* precedence, the company-vs-person identifier split, and the document-level vat_percent being overridden by per-item vat_percent. It does not add format details for dates or currency, but it meaningfully clarifies parameter interplay.

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 an explicit verb and resource ('WRITE: create a document') and immediately narrows scope to invoice variants via the type field. An agent can distinguish this from invbg_create_client and invbg_create_item without opening any schema.

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

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

Gives concrete conditional branches: use client_id for an existing client, otherwise supply to_name + to_address plus company/person identifiers; VAT can be set per document or per item. It also routes to sibling helpers (invbg_list_item_units, invbg_get_exchange_rate, invbg_list_number_sets) for dependent inputs, though it never states an explicit 'do not use this tool when...' exclusion.

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=false and openWorldHint=true, so the mutating and non-idempotent nature is structured data, not new information. The description reinforces the write semantics and adds the endpoint (POST /items), which is minor extra context; it says nothing about retry safety, what happens on duplicate names, or auth requirements.

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?

A single compact sentence with the operation and scope front-loaded and zero filler. The trailing 'POST /items' is arguably irrelevant to an agent invoking an MCP tool but is harmless and short.

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 six-parameter create tool with full schema coverage, optimistic-write annotations, and no output schema, the essentials are covered: what is created, in what domain, and its fields. Missing niceties (currency default, unit lookup, required-field emphasis) are all already available 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 description coverage is 100%, so the schema already documents all six fields including the currency default (BGN) and the quantity_unit cross-reference to invbg_list_item_units. The description merely echoes name/price/unit and adds no format or constraint 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 the specific verb+resource ('add a product or service to the catalogue') and prefixes it with 'WRITE', which cleanly separates it from read siblings like invbg_list_items and invbg_get_item. It does not name those siblings explicitly, but the create-vs-read distinction is unmistakable.

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 no when-to-use or when-not-to-use guidance and names no alternatives. An agent can infer it is the create counterpart to invbg_update_client-style tools, but nothing is stated about prerequisites, duplicate handling, or how it relates to invbg_create_invoice.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds that the result is scoped to the calling API token's identity, which is useful context beyond the annotations, but it says nothing about error behavior or what happens with an invalid token. With annotations carrying the safety burden, a 3 is appropriate.

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

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

A single compact sentence that leads with what is returned, followed by the endpoint. The 'GET /account' trailer is redundant for an agent that already has the tool binding, slightly reducing efficiency.

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

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

No output schema exists, so the description must convey the return shape, and it does list the fields (company id, name, subdomain, plus the user). It is complete enough to call correctly, though it could note that the scope is fixed by the token and that no filters are possible.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to explain. The description correctly implies the scope is determined entirely by the authenticating token rather than by input.

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 specific resource (the company and the user associated with the API token) and lists the key fields returned (id, name, subdomain), so an agent knows exactly what it gets back. It does not explicitly differentiate from the closest sibling, invbg_get_firm, leaving some ambiguity about how the account's company differs from the firm resource.

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

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

There is no guidance on when to call this versus alternatives such as invbg_get_firm, nor any stated preconditions. The only usage signal is implicit: it returns the principal tied to the current token.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds meaningful value beyond that: it discloses what the response contains (full stored detail set) and the endpoint's read semantics, which is important since there is no output 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?

A single front-loaded sentence listing the returned fields followed by the endpoint mapping — every element earns its place 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 read-only single-record fetch with no output schema, the description covers the return contents well, and safety is handled by annotations while parameters are fully documented in the schema. Only a note on error/not-found behavior or sibling routing 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 both parameters are already documented, including the bg/en enum semantics for language. The mention of 'names in both languages' and 'by id' adds light reinforcement but 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 and resource ('One client by id') and enumerates the stored details returned (names in both languages, Bulstat, VAT, address, MOL, code, custom properties), plus the underlying endpoint. This clearly separates it from sibling list tools like invbg_list_clients, though no sibling is named explicitly.

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?

'by id' implies you must already know the identifier, and the schema's client_id description points back to invbg_list_clients. However, the description itself gives no explicit when-to-use/when-not guidance or comparison with list/other get tools, leaving usage only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond that: the rate is the one inv.bg applies to documents, plus the underlying GET endpoint. It says nothing about behaviour for non-business days or unsupported currency 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?

A single front-loaded sentence carrying the direction of conversion, the date scope and the document context, plus a short endpoint reference. Nothing is padded, though the raw path adds little for an agent that already has the tool name.

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

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

For a simple two-parameter read with full schema coverage and no output schema, most of what's needed is present. It still leaves open what the response contains (a single numeric rate), how non-trading days resolve, and how an invalid currency code is reported.

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

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

Schema coverage is 100% and both parameters are documented there, so the baseline is 3. The description does add meaning by fixing BGN as the quote currency and the default date, but repeats the schema's 'default: today' rather than extending it (no format or validation detail beyond the pattern).

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 (exchange rate of a currency to BGN) plus scope (a date, default today), which distinguishes it cleanly from the CRUD siblings. No explicit sibling differentiation is needed since no other tool touches currency rates, but the description never names that contrast.

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

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

'as inv.bg uses it for documents' implies the intended use case — matching the rate inv.bg itself applies — which is a real hint about when to prefer this over an external FX source. However, there is no explicit when/when-not statement and no alternatives or prerequisites (e.g. what to do for non-BGN targets).

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete field list, which is the only disclosure of what comes back (there is no output schema), but says nothing about what happens when the firm profile is unconfigured or about auth requirements.

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?

A single front-loaded sentence listing the returned fields, followed by a short endpoint tag. No filler, though the 'GET /firm' fragment is developer-facing noise to an agent and the opening is a noun phrase rather than a verb.

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 zero-parameter read tool with no output schema, the field enumeration supplies essentially everything an agent needs to use the result. Only edge behavior (no firm configured, error cases) is left unstated, which is a minor gap.

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

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

The tool takes zero parameters, so the baseline of 4 applies; the schema itself is trivially complete. Nothing in the description is needed or expected on the parameter side.

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 identifies the resource as the 'issuing company' (the seller entity) and enumerates the fields returned (name, Bulstat, VAT number, address, MOL, contact email, custom properties). 'Issuing company' implicitly separates it from the many `invbg_get_client`-style siblings, though that contrast is never made 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?

There is no statement of when to call this versus alternatives; 'GET /firm' is an endpoint reference, not usage guidance. An agent must infer from the wording that this is the seller/self record rather than a client lookup.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value by disclosing the returned fields (totals, balances, status, dates) and that comments are optional, but says nothing about error behavior for an unknown id, permissions, or rate limits.

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?

A single compact sentence with the key qualifier ('by id') front-loaded, closed by the endpoint path. The middle becomes a field-list dump, but every item conveys return-shape information that would otherwise be missing without an output schema.

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

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

With no output schema, the description carries the return-shape burden and does so well by enumerating the document contents and optional comments. The remaining gap is failure/error behavior and confirmation of what the endpoint returns when the id does not exist.

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 invoice_id, language and include_comments are fully documented in the schema itself. The description only glancingly hints at include_comments via 'Optionally with its comments' and adds nothing about the language parameter, 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?

Names the resource (invoice document) and the access mode (single document by id) and enumerates the returned content, so it is distinguishable from invbg_list_invoices. It never explicitly names the list sibling as the alternative for multi-document reads, so it stops short of a 5.

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

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

Usage is only implied: fetch one document when you already have its id. There is no explicit when-to-use/when-not or pointer to the list tool in the description text (the useful 'id from invbg_list_invoices, not the printed number' note lives in the schema 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?

Annotations already declare readOnlyHint, non-destructive and openWorld, so the safety profile is covered. Beyond echoing the HTTP route, the description adds nothing: no not-found behavior, no note on whether the response includes nested data or how openWorld affects results.

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

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

Two short fragments, zero waste, and the resource identification is front-loaded. It stops just short of being too thin to stand on its own.

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

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

A two-parameter read tool with no output schema needs little prose, and the description plus the rich schema are just enough to call it. Missing: failure behavior for an invalid id and what the returned record contains.

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 both parameters — the required item_id and the bg/en language enum — are fully documented in the schema, which sets the baseline at 3. The description contributes no additional parameter meaning.

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

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

States a specific verb and resource ('One catalogue item by id') and pins the underlying endpoint GET /items/{id}, so an agent can distinguish it from invbg_list_items and from the other get_* tools. Differentiation is real but implicit — the sibling list is never named.

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 no when/when-not guidance and names no alternative. The only routing hint (that ids come from invbg_list_items) lives in the schema's parameter description, not in the tool 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 declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered; the description's genuinely additive line is that it does not reserve the number, which prevents a wrong assumption. It omits other behavior an agent would want: whether the value can change between calls, and the endpoint's auth/rate-limit characteristics despite 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?

Two short sentences plus the endpoint path, front-loaded with the returned value and followed immediately by the key caveat. Zero filler, nothing buried.

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

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

There is no output schema, so the description must carry the return contract, and it only gestures at it ('the next free document number') without stating the response shape (string vs. object with number/number-set fields). For a trivial single-parameter read this is adequate but not complete.

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

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

Schema coverage is 100% and the enum values are documented in the schema, so the baseline is 3. The description contributes one useful constraint the schema lacks — only the *default* number set is consulted — but adds nothing about how 'custom' or the other enum values behave.

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 resource and scope: the next free document number from the *default* number set for a given document type. That distinguishes it from invbg_list_number_sets and the create_* tools, though it is a noun phrase rather than a verb and never names the sibling it supersedes.

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

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

Usage is only implied — an agent must infer this is called ahead of invbg_create_invoice to preview a number. There is no explicit when-to-use/when-not-to-use guidance and no mention of what to do instead if a non-default number set is needed (list_number_sets is never referenced).

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=true, so the safety profile is covered. The description adds genuine value by disclosing that the response embeds allocations to invoices, but says nothing about what happens for a missing id or how large the allocation set can be.

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 front-loaded sentence with the payload detail first, followed by the REST endpoint for agents that reason about API shape. No filler, though the endpoint path is marginal for an MCP consumer.

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?

A single-parameter read tool with full annotations needs little, and the description covers the key return element (allocations). With no output schema, however, the remaining payment fields and not-found behavior are left undisclosed.

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 already documents payment_id as an inv.bg payment id sourced from invbg_list_payments. The description only restates 'by id', adding nothing beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource ('One payment by id') and adds scope detail that the payment carries its invoice allocations (invoice_payments). This clearly separates it from invbg_list_payments by singular-vs-list, though the sibling is never named.

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 explicit guidance on when to use this versus invbg_list_payments or invbg_get_invoice; the only routing hint ('invbg_list_payments') lives in the parameter schema, not the description. Usage is inferable from 'by id' but never stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /bank/accounts) and, importantly given there is no output schema, the shape of each returned record. It does not say whether inactive/closed accounts are included or how pagination defaults behave.

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?

A single compact sentence front-loads the resource and its fields; nothing is redundant. The trailing 'GET /bank/accounts' is mildly useful for debugging but not strictly needed by an agent.

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

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

For a simple paginated read with no output schema, listing the returned fields is the essential contribution and it is present. However, ordering, inclusion of inactive accounts, and the default page size (left entirely to the schema) are unaddressed, leaving some gaps an agent would want filled.

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 documents page, per_page and the language enum with defaults and limits. The description mentions none of these, which is acceptable at the baseline when 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 names the specific resource (the company's bank accounts) and enumerates the fields each record carries (alias, bank, IBAN, BIC, currency), so an agent knows exactly what comes back. The 'list' verb is only implied through the name/title, and nothing distinguishes this from siblings like invbg_list_bank_transactions or invbg_list_cashboxes.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as invbg_list_cashboxes or invbg_list_bank_transactions, nor any prerequisites (e.g. whether an authenticated firm context is required). Usage is only inferable from the tool name and the listed fields.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds that results are imported records and the semantic of the linked flag. It omits pagination behavior and total/next_page structure, which matters for a 12-param paged listing 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?

Three short sentences, front-loaded with what the tool returns before the usage hint and endpoint. The trailing 'GET /bank/transactions' is mild filler that doesn't help an agent decide or call.

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

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

For a read-only list tool with fully documented params and no output schema, the description is adequate but thin: it doesn't describe the response envelope (pagination, total count, next_page) that the page parameter references, leaving an agent to infer result shape.

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

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

Schema description coverage is 100% with clear enum docs for type and order, so the schema carries the parameter burden. The description reinforces only the linked semantics (reused from the schema) and mentions no parameter beyond that. 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 (list bank transactions) and enumerates the returned fields (amount, date, counterparty, linked-to-document status), which distinguishes it from siblings like invbg_list_bank_accounts or invbg_list_payments. It stops short of naming a close alternative explicitly, but the domain is unambiguous.

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

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

Adds a clear reconciliation use case with the key rule 'linked=false = unmatched', which is genuinely actionable. However, it gives no when-not guidance and doesn't contrast with invbg_list_payments or invbg_list_bank_accounts for overlapping needs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results include names and balances, but it omits pagination behavior and any rate or access considerations, leaving it only modestly additive.

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 very short and front-loaded, with no wasted sentences. The trailing 'GET /cashboxes' is somewhat redundant with the tool name, keeping it from a 5.

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

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

For a simple read-only list operation with no output schema, the description covers the resource and returned fields. However, it lacks pagination context and any note on search behavior, which are relevant given the three optional parameters.

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 parameters page, search, and per_page are fully documented in the schema with defaults and limits. The description adds no parameter meaning beyond what the schema already provides, making baseline 3 appropriate.

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

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

The description states the specific resource (cash registers/cashboxes) and the fields returned (names and balances), plus the endpoint. It does not explicitly distinguish this tool from sibling list operations such as invbg_list_bank_accounts, so it falls 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?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The listing purpose is obvious from the name, but the description adds no usage context.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the returned content (contact names and roles) in the absence of an output schema, and by noting the scope can be one client or all clients.

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

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

Two compact sentences: what the tool returns first, endpoint second. No filler, and the scoping nuance is front-loaded where an agent will read it.

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?

A read-only list tool with fully documented parameters and no output schema; the description supplies the missing return-shape information. Pagination behavior is covered by the schema, so nothing critical is missing, though a note on search semantics would round it out.

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 page, per_page, search, and client_id are all documented in the schema itself. The description only reinforces client_id filtering via '(or of all clients)' and says nothing about search or paging semantics, 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 resource (client contacts) and the fields returned (names, roles), plus the backing endpoint 'GET /client-contacts'. It's unmistakable against the sibling list since no other sibling deals with contacts, but it never explicitly differentiates itself from invbg_get_client or invbg_list_clients, keeping it below 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?

The parenthetical '(or of all clients)' hints that omitting client_id returns everything, but there is no explicit when-to-use statement, no mention of the search parameter's role, and no guidance on when to prefer invbg_get_client over this tool. Usage is only implied.

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

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

The description details the specific data points retrieved (name, Bulstat, VAT number, etc.), which provides context on the response payload. Since the annotations already handle the safety profile (readOnlyHint), the description adds useful scope information without contradicting the defined 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?

It is concise, summarizing the tool's utility and scope in a single, readable sentence. The key function (List or search) and the main attributes are front-loaded.

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

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

Given the high complexity of the 12 input parameters, the description is adequate for defining what the *results* look like. However, it remains incomplete by not providing context on the search complexity, performance constraints, or guidance on the appropriate use cases versus other sibling tools.

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 100% schema description coverage, the baseline is already moderate. The description reiterates the semantic content of the client data (e.g., 'Bulstat', 'whether it is a person'), which confirms the type of records the parameters will retrieve, but doesn't add complex filtering logic not already implied by 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 tool clearly states its function: to 'List or search clients (customers)'. This verb-resource structure is clear, and the phrase 'customers' helps distinguish it conceptually from a general 'client' record.

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 lacks guidance on *when* to use this tool relative to alternatives. It provides a simple summary of capability but does not advise the agent on specific scenarios for list/search operations versus targeted lookups (e.g., invbg_get_client).

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 destructiveHint=false, so the safety profile is given. The description adds genuine value beyond annotations by naming the HTTP endpoint and, importantly, describing the return shape (number, client, totals, balance_paid, balance_due, dates) in the absence of an output 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?

Three short sentences, front-loaded with the resource and filters, followed by the returned fields and endpoint. No filler; every clause 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 21-param list tool with no output schema, the description covers what is filtered and what comes back, and annotations cover safety. Minor gaps remain (pagination workflow is only in schema, no note on combining filters or sort defaults), but it is broadly complete.

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

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

Schema coverage is 100%, so every one of the 21 parameters is already documented in the schema. The description's filter enumeration largely restates what the schema provides without adding syntax, interaction, or semantics beyond it; baseline 3 is appropriate.

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

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

States a specific verb ('List') and resource ('documents: tax invoices, proformas, debit and credit notes'), then enumerates the filter dimensions and the fields returned per row. An agent can immediately tell this is the collection/query endpoint, distinct from single-record siblings like invbg_get_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?

The description implies usage (query documents with filters) but never states when to prefer this over siblings or when not to use it, nor prerequisites. The only routing hint is the schema's client_id note referencing invbg_list_clients, not the description itself.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results carry codes and include custom types, but says nothing about whether inactive types are returned, whether the list is company-scoped by auth context, or whether it paginates.

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

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

Two short sentences, front-loaded with the resource and its contents, with no padding. The trailing 'GET /invoices/types' is slightly redundant but harmless.

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 zero-parameter, read-only lookup with no output schema, the description gives an adequate picture of what comes back (types plus codes). Minor gaps: no mention of filtering, ordering, or whether the company context comes implicitly from the session.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the only added semantic value is that results include custom types, not just built-in ones.

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 names the resource precisely (all document types of the company) and enumerates subtypes (tax invoice, proforma, debit/credit note, custom types), so an agent can distinguish it from neighbours like invbg_list_number_sets or invbg_list_vat_exemption_reasons. It lacks an explicit verb but 'All document types ... with their codes' is unambiguous enough.

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

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

There is no explicit when-to-use statement, no prerequisites, and no comparison to sibling list tools. Usage is only implied: an agent can infer this is reference data to obtain type codes before calling invbg_create_invoice, but the description never says so.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds the HTTP endpoint (GET /items) and the returned field list, which is modest extra context, but it discloses nothing about pagination limits, rate limits, or result size — and with openWorldHint=true, some note on external data variability would help.

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

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

Two short fragments, front-loaded with the resource identity, with zero filler. It is arguably clipped to the point of under-specification, but nothing in it is wasted.

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

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

With 7 optional parameters and no output schema, the description should carry more weight: it hints at the response shape via the field list but omits the pagination contract (next_page, per_page defaults) and does not clarify that all parameters are optional filters. Serviceable but leaves clear gaps an agent must fill from the schema alone.

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; the description goes slightly beyond by naming the catalogue attributes (name, price, currency, unit, tags) that the filtering and sorting parameters operate over, helping the agent infer useful values for search, order_by and tag_name. It still does not explain page/per_page interplay.

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 identifies the resource as a product/service catalogue and lists the fields it exposes, which tells the agent what kind of data comes back. However, it never uses a verb like "list" or states scope (all items vs. filtered), and it says nothing to distinguish it from sibling invbg_get_item or invbg_create_item beyond the plural noun.

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

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

There is no guidance on when to use this tool versus invbg_get_item (single record) or invbg_list_item_units, nor any mention of pagination workflow such as following next_page. The only usage hint lives in the schema's parameter descriptions, not the tool 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the backing endpoint (GET /items/units), which signals a static reference list, but says nothing about return shape, pagination, or whether the list is firm-specific.

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

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

Two short fragments, zero waste, with the highest-value fact (what these units are used for) front-loaded. Slightly telegraphic but nothing needs cutting.

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 one-parameter read-only reference lookup with no output schema, this is enough to select and call the tool correctly. A note on whether the response is a flat value list or objects with ids would make 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 100% and the single 'language' parameter has an enum plus a clear description in the schema itself. The description adds no meaning about how language affects the returned unit names, so the baseline 3 applies.

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

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

The description names the resource (units of measure) and, more usefully, states its role: the values accepted as quantity_unit on items and invoice lines. It is not confused with any sibling, though it omits an explicit verb (the title supplies '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?

By saying these are the accepted quantity_unit values, it implies when to call it – as a lookup before creating or updating items/invoice lines. It never states that explicitly, nor does it exclude any case or name an 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /invoices/number-sets) and the id-consuming relationship, but says nothing about result volume beyond the schema's paging params or ordering.

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 tight sentence: resource definition first, then the actionable instruction, then the endpoint. No filler and nothing important buried.

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-param, no-output-schema list tool this covers purpose, the shape of the results (number sets with ids), and how to use them downstream. Slightly short of complete because it doesn't hint at other fields returned or ordering, and doesn't contrast with invbg_get_next_invoice_number.

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

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

Schema coverage is 100% and both parameters (page, per_page) are fully documented in the schema, including the next_page chaining hint. The description adds no input-parameter detail of its own; its extra meaning concerns the returned id, not the inputs. 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 exact resource (the company's invoice number sets, glossed as separate numbering series), notes that ids are returned, and ties it to a consumer (invbg_create_invoice). The parenthetical definition alone distinguishes it from sibling list tools like invbg_list_invoice_types.

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 to pass an id as number_set to invbg_create_invoice, which tells the agent the concrete situation this tool serves. It does not address the nearest alternative, invbg_get_next_invoice_number, so the when-not guidance is missing.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this is a GET endpoint and sketches the payload (codes plus names), which partially compensates for the absent output schema, but it says nothing about ordering, completeness of the list, or whether codes are firm-specific.

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

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

Two short sentences, front-loaded with what the caller gets. The trailing raw endpoint path 'GET /invoices/payment-methods' is marginally useful for orientation but borders on 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 zero-required-param reference lister with no output schema, the description conveys the essential return content (codes and names) and the schema covers the one optional parameter. Missing only minor details such as ordering or whether the list is static across firms.

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%: the single optional 'language' enum param is fully documented in the schema, including the bg default and the fallback behavior. The description adds nothing 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?

The description identifies the exact resource: the payment-method codes a record accepts, with their human-readable names, and gives examples (card, card, cash). That is enough to distinguish it from sibling enum-lookup tools like list_invoice_items or list_vat_exemption_reasons, though it never explicitly frames the operation as 'list' or contrasts with those 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?

There is no explicit when-to-use statement or named alternative. Usage is only implied by the phrase 'the payment method codes a document accepts', which suggests it is a reference lookup for populating invoice/payment fields. An agent can infer the context but must do the work itself.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the returned payment fields, including invoice allocation (amount_used) and remaining balance (amount_left), but does not discuss pagination behavior or result ordering beyond what the schema states.

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 a single front-loaded sentence plus the endpoint, with no wasted text. It efficiently communicates the resource and the notable return 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 usefully names the key payment fields and the allocation/remaining amounts an agent will receive. Combined with the fully described schema and read-only annotations, this is largely complete, though it could mention pagination or default sorting more explicitly.

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

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

Schema description coverage is 100%, so all 14 parameters are thoroughly documented in the schema itself. The description does not add parameter-level meaning or filter syntax, but the baseline for fully documented parameters is 3.

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 identifies the resource clearly: recorded income and expense payments, with key fields such as amount, method, date, counterparty, amount_used, and amount_left. It also gives the endpoint GET /payments, making the listing purpose evident, though it does not explicitly distinguish itself from invbg_get_payment or invbg_list_bank_transactions.

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

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

There is no explicit guidance on when to use this tool versus invbg_get_payment or the bank-transaction listing tools. The description implies a generic payment listing but offers no exclusions, prerequisites, or alternative-selection guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds the endpoint and the fact that this is legal reference data, but says nothing about the shape of the returned records (code/name pairs) beyond the schema's hint that names may be localized.

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

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

Two compact sentences with zero filler: purpose and downstream usage are front-loaded, and the raw endpoint is appended as a trailing identifier. Nothing 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 zero-required-param lookup with full schema coverage and no output schema, the description covers purpose and the consuming tool, which is enough to call it correctly. A brief note on what a returned reason record contains would close the last gap, since there is no output schema to fall back on.

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

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

Schema description coverage is 100% and the single `language` parameter carries its own enum and explanation (bg default, en where available), so the schema does the heavy lifting. The description adds nothing about the parameter, which is the expected baseline for a one-param tool with full schema coverage.

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

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

The description identifies the resource precisely (legal reasons for issuing a document without VAT) and the endpoint GET /invoices/without-vat-reasons, which tells an agent this is a reference-data lookup. It is distinguishable from most siblings, though it does not explicitly contrast with the other list_* enumeration tools (invoice_types, payment_methods, item_units).

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 states the downstream use: pick one as vat_exemption_reason in invbg_create_invoice, which is exactly the when-to-use context an agent needs. There are no stated exclusions or prerequisites, but for a pure enumeration tool that is a minor gap.

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 a non-idempotent, non-readonly, open-world write; the description adds the part that annotations cannot express: the operation is two sequential API calls and can leave a payment recorded while the allocation fails. That partial-state disclosure is the critical behavioral detail, though auth/permission requirements and what a success returns are still unstated.

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

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

Three sentences, front-loaded with the operation class and effect, then the call sequence, then the failure mode. No sentence is redundant and nothing is buried.

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 write tool with no output schema, the description covers the side effects, the two-step mechanism, and the failure state, which is what an agent needs to invoke it safely. The remaining gap is that a successful return value (e.g., payment id) is only implied via the error case.

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% across all 8 parameters, including the currency_rate/BGN explanation and the payment_processor enum, so the schema carries this dimension. The description adds no parameter-level guidance of its own, which is the correct baseline of 3 when the schema is complete.

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?

"WRITE: record a payment received for a document and allocate it" gives a specific verb, resource, and scope. The stated effect on balance_paid/balance_due and payment status distinguishes it from any read sibling like invbg_get_payment or invbg_list_payments.

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 "WRITE" prefix plus the partial-failure advice make the intended use clear, and it routes to invbg_get_payment when the allocation step fails. It does not name any competing alternative for recording payments, so the routing is only addressed for the recovery path, not the primary 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?

Beyond the annotations, the description adds the critical behavioral facts that the email is sent immediately and cannot be recalled, and clarifies that delivery can be a link or an attached file. It does not contradict the annotations: openWorldHint matches the external email side effect, and destructiveHint=false remains reasonable because no data is deleted.

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 three short, front-loaded sentences with no filler. The 'WRITE' prefix, behavioral warning, and endpoint each earn their place.

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

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

For a 7-parameter tool with full schema coverage and no output schema, the description covers the core action, delivery modes, and irreversible side effect. It does not describe success/failure behavior, but that is a minor gap given the complete input 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 100%, so every parameter is already documented, including defaults for subject, delivery, and language. The description reinforces the link-vs-file delivery choice but adds no syntax, constraints, or default details 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 uses a specific verb (email) and resource (a document, specifically an invoice via the endpoint), and states the two delivery modes. An agent can immediately tell this is a send-invoice-by-email action, and no sibling tool overlaps with that purpose.

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 makes the operation's context clear with the explicit 'WRITE' marker and the endpoint, and the irreversibility warning signals that it should be used deliberately. It does not name alternatives or state when not to use it, but among the sibling tools there is no competing email-sending operation.

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 this is a non-read-only, destructive, idempotent, open-world write operation. The description adds useful PATCH semantics by saying only passed fields are changed, but it does not disclose permission requirements, side effects, or what makes the operation destructive.

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 compact sentences with the write intent and partial-update behavior front-loaded. There is no filler or redundancy.

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

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

For a destructive update tool with 11 parameters and no output schema, the description is minimally adequate: annotations cover safety hints and the description covers partial-update behavior. It still leaves field-level parameter meaning and update failure behavior unexplained.

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

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

Schema description coverage is only 9%, with essentially just client_id documented, so the description must compensate for ten undocumented fields. 'Only the fields you pass are changed' is a valuable partial-update semantic, but it does not explain the meaning of fields such as mol, bulstat, or is_reg_vat.

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

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

The description states a specific verb and resource: 'change fields of an existing client', with the endpoint PATCH /clients/{id}. This clearly distinguishes it from creation and retrieval tools such as invbg_create_client and invbg_get_client, though it does not explicitly name those 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 phrase 'change fields of an existing client' and the parenthetical partial-update note imply when to use this tool rather than creating or fetching a client. However, it gives no explicit alternatives, prerequisites, or 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.