SmartBill MCP by usefulapi

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

Annotations already declare destructiveHint=true. The description adds meaningful behavioral context beyond that: the operation is reversible via smartbill_restore_estimate, and it specifies the PUT endpoint. It still omits auth requirements or exactly what state is invalidated, so 4 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 front-loaded sentence plus the endpoint; every word carries information and there is 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 cancellation tool with no output schema, the description supplies purpose, undo path, and endpoint. It is largely complete, though it could say a bit more about prerequisites or post-cancellation state.

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 series_name and number are fully documented in the schema. The description adds no parameter-level syntax or format details beyond that, 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 (cancel) and resource (proforma), and explicitly names restore_estimate as the inverse operation, distinguishing it from siblings. The HTTP endpoint 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?

Provides clear context for cancelling a proforma and names smartbill_restore_estimate as the undo path. However, it does not state explicit prerequisites or when not to use it, so it falls short of a full 5.

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

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

Annotations only supply destructiveHint=true, so the description adds real value: it discloses that the invoice is retained as cancelled rather than deleted, that fiscal status changes, that user confirmation is required, and that the action is reversible via restore. It stops short of stating permission/authentication requirements or any side effects on downstream documents (e.g. payments already recorded).

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 plus an endpoint fragment; the persistence behavior and the sibling pointer are front-loaded where they matter. The trailing 'PUT /invoice/cancel' is slightly redundant for an agent that never issues HTTP directly, but it is 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 two-parameter, no-output-schema mutation tool whose parameters are fully documented in the schema, the description covers what an agent needs: the state change, its reversibility, and the confirmation requirement. Only the cancel-vs-reverse distinction is left unaddressed.

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

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

Schema coverage is 100%, and the two parameter descriptions already explain the leading-zero convention for number and point to smartbill_list_series for series_name. The description adds no parameter-level meaning beyond that, 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 ('Cancel an existing invoice') and immediately scopes it with 'it stays in the books as cancelled', which distinguishes it from hard-delete semantics. It also names the sibling that reverses the effect (smartbill_restore_invoice), so the agent can place it in the lifecycle 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 operational guidance — confirm with the user, use smartbill_restore_invoice to undo — which is unusually strong for a mutation tool. It does not, however, distinguish this from smartbill_reverse_invoice, a sibling with an overlapping but materially different effect, leaving that choice to inference.

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

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

Annotations declare destructiveHint=true; the description adds that the default is a DRAFT with no number and that draft=false consumes the next series number — useful behavioral context for a mutation. It does not itself restate the 'cannot be undone' warning (that lives in the schema), so it stops short of full disclosure.

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

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

Four front-loaded sentences, each earning its place: purpose, draft semantics, sibling disambiguation, and return/endpoint. 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?

Despite no output schema, the description names the return fields (series, number, documentId, links) and the endpoint, and covers the draft/issue distinction — everything an agent needs to call it correctly given the rich 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 baseline is 3. The description restates the draft default and the return fields, adding little meaning beyond what the schema already documents in detail for every 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 specific verb+resource ('Create a proforma (estimate)') plus scope ('for a client with product/service lines') and explicitly distinguishes itself from a sibling concept by noting 'A proforma is not a fiscal invoice', separating it from smartbill_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 clear context on when the draft-vs-issued distinction matters and states the default, but does not explicitly name alternative siblings (e.g. smartbill_create_invoice) or conditions that would route to them. Clear usage without explicit 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 only supply destructiveHint=true; the description carries the rest and does so well: draft saves with no number, draft=false consumes the next series number, cannot be deleted or edited through this server, can only be cancelled or reversed (storno), and may be transmitted to ANAF depending on e-Factura setup. That is exactly the irreversibility/authorization context an agent needs before a write.

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

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

A single dense paragraph that front-loads purpose, then the draft/issue decision, then the return payload, then the endpoint. Every sentence carries decision-relevant information; nothing is redundant with the schema.

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

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

No output schema exists, so the description usefully enumerates the return fields (series, number, documentId, documentUrl needing login, documentViewUrl as a public PDF). Combined with the mutation semantics and the sibling list lookups it references, 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 description coverage is 100%, so every parameter (including the nested client and products objects) is already documented in the schema and the baseline is 3. The description restates the draft flag's meaning and names sibling lookups for series/taxes, but adds no per-parameter syntax or format 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, resource and content ("Create an invoice for a client with product/service lines") and immediately frames the two operating modes. An agent can distinguish it from smartbill_create_invoice_from_estimate and smartbill_create_estimate 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?

Explicitly says when to keep the default draft (review in SmartBill Cloud) and when to pass draft=false (user explicitly wants it issued now), plus a required confirm-with-user step. It does not, however, route the agent between this tool and the sibling smartbill_create_invoice_from_estimate.

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 single destructiveHint annotation: it discloses that a draft has no number, that issuing consumes the next number of the series, that issuing cannot be undone from the API, that the document may be transmitted to e-Factura / ANAF, and the notable negative side effect that stock is NOT discharged. These are exactly the consequences an agent needs before mutating state.

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 purpose, then the draft/issue consequence, then the stock caveat, closing with the endpoint token. Dense but nearly every clause carries information; the trailing 'POST /invoice/v2 (useEstimateDetails)' is implementation detail of marginal value to an agent already given a tool.

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

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

For a 5-parameter mutation with no output schema and only a destructiveHint annotation, the description covers the critical side effects and irreversibility. It does not describe what is returned on success (e.g. the assigned number/series), which would help the agent confirm issuing behavior, and it omits sibling differentiation against smartbill_create_invoice.

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 including the draft/today defaults and min/max lengths is already documented in the schema. The description adds the source-copy behavior but no parameter-level detail 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+resource+source: 'Create an invoice from an existing proforma (client and lines are copied from it)'. The parenthetical clarifies the copy semantics, which differentiates it from the sibling smartbill_create_invoice that presumably starts from scratch.

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 conditional for the draft flag ('Default is a DRAFT; with draft=false the invoice is ISSUED...'), and the schema reinforces the 'pass false ONLY when the user explicitly wants it ISSUED now' rule. However, the description never states when to choose this tool over smartbill_create_invoice, so the alternative-selection guidance is left implicit.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavioral context beyond that: the authentication requirement (API V3 token) and the underlying endpoint GET /v3/companies/{cif}/clients/{id}. It stops short of discussing permissions 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?

Two tight sentences: identity/return payload first, then the auth and endpoint detail. No filler, every clause earns its place.

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

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

For a single-parameter read tool, the description lists the returned fields (name, CIF, address, bank, contact, VAT flag, delivery addresses), states the auth requirement, and provides the endpoint. Nothing an agent needs to invoke it correctly is missing, even without an output schema.

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

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

Schema coverage is 100% and the single id parameter is documented in the schema with its pattern and 'from the list tool' hint, so the description's mention of the cus_ format is largely redundant. Baseline 3 applies when the schema carries the semantics.

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

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

States a specific verb+resource ('One client by V3 id') and enumerates the returned fields, making it clearly distinguishable from the sibling list_clients and get_supplier 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?

Notes the id comes 'from the list tool', implying the list-then-fetch workflow, and states the API V3 token requirement. It does not explicitly contrast with list_clients or state when-not to use it, but the routing 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 readOnlyHint=true, so safety is covered. The description goes beyond that by disclosing a non-obvious data trait: a draft invoice appears with an empty number. It also names the underlying endpoint. It still says nothing about pagination or result size limits, keeping it short of a 5.

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

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

Two short sentences plus an endpoint reference, with the primary behavior (whether it was invoiced) front-loaded. Every sentence carries information and nothing is padded.

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

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

For a simple two-parameter read tool with full schema coverage and annotations, the description is nearly sufficient, and it partially covers the return shape (invoices with series/number, empty number for drafts) despite the absence of an output schema. It is only missing guidance on empty results or multiple invoices returned.

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 (series_name, number) are already documented as the proforma's identifiers. The description's mention of 'series, number' refers to the returned invoices rather than adding input semantics, so it neither clarifies nor contradicts 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?

The description names a specific resource (invoices generated from a proforma) and its scope (whether invoiced plus the series/number pairs), which clearly separates it from creation/cancellation siblings like smartbill_create_invoice_from_estimate. It is not an explicit verb+resource statement, but the intent 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?

Usage is implied: an agent reads this as the way to check whether a proforma has already been invoiced. However, no alternative is named (e.g., a general invoice lookup) and no conditions or exclusions are stated, so the agent must infer when this beats other lookups.

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 readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral value by disclosing the shape of the result (three amounts plus a paid flag), which is otherwise undocumented since there is no output schema. It does not contradict the annotations.

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

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

Two tight sentences with the value proposition front-loaded; the only near-waste is the trailing 'GET /invoice/paymentstatus' endpoint token, which restates the obvious but is cheap.

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 only two fully documented parameters, the description fairly compensates by naming the returned amounts and paid flag. It stops short of note on error behavior (e.g., unknown series/number), which 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%: the schema already documents 'number' (with leading-zero guidance) and 'series_name' (pointing at smartbill_list_series). The description adds no parameter-level detail beyond that, which lands at the baseline for fully documented schemas.

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 ('whether an invoice is paid and how much remains') and immediately enumerates the exact fields returned (invoiceTotalAmount, paidAmount, unpaidAmount, paid flag), which cleanly separates it from the write-side sibling smartbill_record_invoice_payment.

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

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

There is no when-to-use guidance, no mention of the read-vs-write alternative (smartbill_record_invoice_payment), and no prerequisites such as the invoice needing to exist. Usage is only inferable from the tool 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?

readOnlyHint=true already declares this a safe read, so the bar is lower; the description adds genuinely useful context — the required V3 token and the underlying GET endpoint. It does not describe the response shape or error behavior, but the auth requirement is a meaningful addition 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?

Three compact sentences with zero filler; the identifying scope ('One product or service by V3 id') is front-loaded, followed by the prerequisites and endpoint. Every sentence carries distinct information.

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

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

For a simple getter with no output schema, the description covers identification, auth, and the endpoint, but never says what is returned (fields, not-found behavior, or whether it errors on a missing product). That gap is minor but real given 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% with only one param, so the schema already documents 'id' fully, including the prod_ pattern. The description repeats the 'prod_...' format without adding syntax or lookup guidance beyond what the schema states, 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 (retrieve one product/service) and scopes it precisely by the V3 id format 'prod_...'. The singular 'One product or service' implicitly contrasts with the sibling list_products, but no sibling is named explicitly, so it stops short of full 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?

The description implies usage (fetch a single known product by id) and states a prerequisite (API V3 token), but gives no explicit when-to-use vs when-not guidance. It never names list_products as the way to obtain the id, leaving routing 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?

With readOnlyHint=true already covering the safety profile, the description adds useful behavior: the stock-module prerequisite, the case-sensitive matching rule for warehouse_name, and the all-products fallback when unfiltered. It does not mention pagination or result shape, but that is a minor gap given the annotation coverage.

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

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

Three tight, front-loaded sentences with no filler; scope, prerequisite, and filters appear in order of importance. The trailing 'GET /stocks' endpoint reference is minor implementation noise but does not detract materially.

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 filtered query with no output schema, the description supplies prerequisite, filter semantics, and default behavior. What remains unsaid (return format, pagination) is minor against an annotation that already certifies a safe read.

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

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

At 50% schema coverage, the description carries extra weight and does list all three optional filters by name and explains the default when none are supplied. It reinforces the case-sensitivity of warehouse_name (already in schema) but leaves product_name/product_code without syntax detail, which is acceptable for free-text identifiers.

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 ('Stock quantities per warehouse as of a date') with clear scope. No sibling tool retrieves stock, so the agent can distinguish it from the list/get/estimate/invoice cluster immediately. The description also names the parameter surface, making purpose 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?

Gives a clear prerequisite ('needs the SmartBill stock module') and specifies the default behavior when filters are omitted ('No filters = all products in all warehouses'). It doesn't name an alternative sibling, but none exists in the tool set, so there is little more to say.

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, so safety is covered. The description adds meaningful context beyond that: it requires the API V3 token and specifies the exact endpoint being called. It does not disclose error behavior for missing ids or rate limits, keeping it short of a 5.

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

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

Three short clauses, each carrying information: identifier scope, auth requirement, and endpoint. Front-loaded with the core purpose. 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 single-item read with one fully-documented parameter and read-only annotations, the description covers what's needed. It omits what the response contains, but with no output schema this leaves a small gap; still adequate for the tool's simplicity.

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 parameter id and its pattern are fully documented in the schema. The description adds only the format hint '(sup_...)' which is already present in the schema pattern, so no meaningful semantic gain. 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 (get) and resource (one supplier by V3 id), and the identifier format (sup_...) distinguishes it from list_suppliers. The HTTP endpoint is even provided, removing all ambiguity.

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 '(sup_...)' and 'from the list tool' imply you obtain ids via the list_suppliers sibling, giving implicit context. But there is no explicit when-to-use vs. the get_client/get_product siblings, nor a stated alternative for fetching multiple suppliers.

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 readOnlyHint, so the description carries the rest and does well: it discloses auth requirement ('Needs the API V3 token') and the cursor pagination mechanics. It omits return shape and rate limit context, so short of a 5.

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

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

Three tight sentences plus an endpoint reference; front-loaded with purpose, then filters, then auth and pagination. 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?

A read-only list tool with no output schema and fully documented params; the description covers filters, auth, and pagination. Minor omission: no note on default page size or result ordering, but the schema covers limit.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value by pre-classifying the filters (partial/case-insensitive for name, exact for code and CIF) and explaining the cursor pagination protocol that the schema only hints at.

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

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

Specific verb (list) + resource (clients) with the exact filter semantics spelled out (name partial/case-insensitive, code exact, CIF exact). Distinguishes itself from the sibling smartbill_get_client by being the bulk/search variant.

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

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

Gives clear context for when to use it (bulk list with optional filters) and describes the pagination contract ('pass next_args as next call's arguments'). It does not explicitly name smartbill_get_client as the single-client alternative, so not a full 5.

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

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

readOnlyHint=true already declares the safe-read profile, yet the description adds real value: the API V3 token requirement and the cursor-paging contract (pass the reply's next_args as the next call's arguments). No rate limits, failure modes, or empty-result behavior are disclosed, so it is not a 5.

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

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

Three tight sentences with the catalog scope, filter modes, auth prerequisite, pagination contract, and endpoint path all front-loaded in that order. No filler, no repeated 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?

With no output schema, the description compensates by naming the fields returned and explaining the next_args/previous_args cursor handoff, plus the auth prerequisite. It leaves result ordering and empty-result behavior unstated, so it is complete but not exhaustive.

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 five parameters are already documented, including the after/before cursors and the 1-100 limit default. The description's "whole-word match" and "exact" phrasing largely restates the schema's "A word of the product name" and "Exact product code (case-sensitive)", adding only marginal meaning, which fits the baseline 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?

States a specific verb and resource (list the product and service catalog) and enumerates the returned fields (price, unit, VAT rate, currency), so its scope is unambiguous versus the singular smartbill_get_product. However, it never names a sibling or explicitly distinguishes itself from smartbill_list_taxes/list_vat_rates, so it falls short of the 5 benchmark.

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?

"Optionally filtered by name ... or internal code" implies when the filters are useful, and the token prerequisite is stated. But there is no when-not guidance and no pointer to smartbill_get_product for single-record lookup, so usage must be inferred.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower; the description still adds useful context by disclosing the endpoint (GET /series) and the returned content ('with their next number'), which matters since there is no output schema. It omits auth requirements, pagination, or ordering, hence not a 5.

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

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

Three tight sentences with the core purpose front-loaded. One sentence duplicates the schema enum mapping verbatim, which is mild redundancy but the overall structure remains efficient.

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

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

No output schema exists, and the description partially compensates by stating that series are returned with their next number, plus the prerequisite relationship to invoice/proforma tools. For a simple one-param read tool this is nearly complete; only auth and result-shape details are absent.

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 enum parameter is already documented in the schema, so baseline is 3. The description's 'f = invoice series, p = proforma, c = receipt; omit for all' largely restates the schema enum mapping without adding new meaning.

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

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

States a specific verb and resource ('List the document series configured in SmartBill Cloud') plus the payload detail that distinguishes it ('with their next number'). An agent can distinguish it from sibling list tools (list_clients, list_taxes, list_warehouses) purely from the name and description.

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?

'Invoice and proforma tools need a series name from here' explicitly routes the agent to this tool as a prerequisite for the create/estimate siblings. It gives clear when-to-use context but no explicit exclusions or naming of a specific alternative tool.

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the API V3 token requirement and the cursor contract (feed the reply's next_args back as arguments), which an agent cannot infer from 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?

Three tight sentences, front-loaded with the core purpose and filters, then auth, then paging, then the endpoint. Nothing is redundant and every clause carries information.

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

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

For a paged list tool with no output schema, the description covers the essentials an agent needs: filters, credentials, and the next_args pagination loop. It stops short of hinting at the supplier record shape or page-size defaults, but the operational contract is 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 description's filter notes (partial name, exact code/CIF) largely restate the schema's own descriptions. It adds no format or edge-case detail beyond what the parameter definitions already carry, 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 (List) and resource (suppliers) plus the precise filter semantics: name partial, code and CIF exact. This cleanly separates it from smartbill_get_supplier and smartbill_list_clients 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 operational context: which filters exist, that the V3 token is required, and how to continue paging via next_args. It does not explicitly say when to prefer smartbill_get_supplier over this list tool, so it stops short of naming alternatives/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 declare readOnlyHint=true, so the safety profile is covered, but the description adds real context beyond them: it discloses the V1 auth constraint (works without a V3 token) and names the underlying endpoint (GET /tax). It says nothing about rate limits or latency, but for a static config lookup that is minor.

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, all front-loaded: what it returns, how to use the results, and the auth caveat plus endpoint. No filler, and the endpoint reference is compactly placed at the end.

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 no parameters, the description carries the load well by naming the returned fields (name and percentage) and the auth requirement. The only loose end is that the overlap with the sibling smartbill_list_vat_rates is left for the agent to resolve from the '(V1)' title and the V3-token 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The extra sentence about tax_name/tax_percentage describes how the returned values are consumed elsewhere, which is useful but belongs to usage rather than parameter semantics.

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

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

States a specific verb and resource (list the VAT rates configured in the account) plus the returned fields (name and percentage), which is far more than the title alone. However, it never names the near-duplicate sibling smartbill_list_vat_rates, so the agent must infer from 'V1'/'Works without a V3 token' which of the two VAT-listing tools to pick.

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

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

Gives clear context for when this tool is the right one ('Works without a V3 token'), which implicitly routes the agent here when no V3 token exists, and even explains downstream usage of the results (name as tax_name, percentage as tax_percentage on document lines). It stops short of explicitly naming the alternative to use when a V3 token is available.

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, so the safe-read profile is covered. The description adds pagination behavior ('cursor paged: pass the reply's next_args as the next call's arguments') and the token requirement, which are real traits 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?

Three dense sentences with the returned fields, filters, token/alternative note, pagination, and endpoint all front-loaded. No filler; every clause earns its place.

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

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

For a read-only list tool with no output schema, the description enumerates the returned fields and explains cursor pagination, so an agent has everything needed to call and iterate 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%, so the baseline is 3. The description adds useful semantics by clarifying that name is a partial match and percentage is exact, and by tying the next_args cursor value to the after/before parameters.

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 VAT rates) and enumerates the returned fields (ids, name, percentage, reverse-charge flag). It also distinguishes itself from the sibling smartbill_list_taxes by noting the token difference, so an agent can tell them apart.

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

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

Explicitly names the alternative (smartbill_list_taxes) and the condition that differentiates it (no V3 token needed), and states the filter modes. The routing rule is implied rather than spelled out as 'use X when you lack the token', so it falls just short of a 5.

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

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

Annotations only declare readOnlyHint=true; the description adds real context beyond that: the API V3 token requirement, the cursor-paging contract ('pass the reply's next_args as the next call's arguments'), and the underlying endpoint. It stops short of stating any rate limits or filtering constraints.

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 purpose, then auth, then paging, then endpoint — a sensible order with little waste. The trailing raw endpoint string is marginally redundant given the tool name but does help an agent reason about the 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?

With no output schema, the description compensates by naming the returned fields, and it covers auth and pagination. It is nearly complete for a simple read-only list tool, though it doesn't describe default paging size or empty-result 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 description coverage is 100%, so name/after/before/limit are already fully documented in the schema, and the description largely restates the cursor behavior already present in 'after'. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

States a specific verb+resource ('List warehouses') and enumerates the returned fields (name, type en gros / en detail, keeper, address), which no sibling covers. An agent can distinguish it from smartbill_list_clients/list_products/list_series at a glance.

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 the use case (retrieve warehouses) and gives the paging workflow, but never states when to call it versus an alternative or any precondition beyond the token requirement. Usage 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 only supply destructiveHint=true, so the description carries most of the burden and does so well: it discloses that Chitanta issues a numbered receipt that 'cannot be undone from this server', that other types create no document, and that invoice paid status in the books changes. It stops short of covering failure/idempotency behavior for multi-invoice or partial-value cases, so it is strong but not exhaustive.

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 built as a single dense semicolon-chained sentence with no filler; every clause adds a constraint, exclusion or side effect. The trade-off is readability — no line breaks or visual grouping across five distinct behaviors.

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, 7-parameter write with no output schema, the description covers the essentials: what it mutates, irreversibility, which types create documents, and an unsupported case. It leaves gaps on multi-invoice/partial-failure semantics and required permissions, which an agent would need before committing a bulk collection.

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 restates what the schema already documents (value = partial, single invoice; Chitanta needs receipt_series) and adds only one genuinely new semantic point: client and amount are derived from the invoices rather than supplied, which explains why no amount/payer parameter exists.

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 ('Record a collection (incasare) against one or more issued invoices') and immediately scopes it as a write-to-books operation, which separates it from read-side siblings like smartbill_get_invoice_payment_status. The sync name/description language (incasare, Chitanta) matches the domain so an agent knows exactly which action is being invoked.

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 conditional guidance: 'value (single invoice only)' for partial payments, 'type Chitanta' for a numbered receipt, an explicit exclusion ('Fiscal receipts (Bon) are not supported'), and an operational instruction ('confirm with the user'). It never names an alternative sibling tool for the excluded/near-miss cases, so routing is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, so the mutating nature is signaled; the description adds the useful precondition that the target must be in a cancelled state. It does not explain what the restore actually changes (number reuse, series occupancy, whether it can be undone) or any auth/rate constraints.

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 action and condition. The trailing 'PUT /estimate/restore' is mild implementation trivia but costs almost nothing.

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, the description covers purpose and precondition adequately, but leaves out post-restore state effects and failure modes an agent would want before calling a destructive operation.

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% (both number and series_name are documented), so the schema carries the parameter burden and the description adds no format, syntax, or case-sensitivity detail. 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 (Restore) and resource (proforma/estimate) plus the state precondition that it must have been cancelled, which separates it from smartbill_cancel_estimate and smartbill_restore_invoice. Minor terminology drift between the tool name (estimate) and the description (proforma) leaves a small ambiguity about whether these are the same object type.

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 when-to-use guidance beyond the implied 'only cancelled proformas' condition. It never names the alternative sibling (smartbill_restore_invoice) to disambiguate invoice vs proforma restoration, nor states prerequisites such as required permissions or whether the original series/number must still be free.

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 supply only destructiveHint=true, so the description carries the rest of the burden. It usefully declares the state transition (cancelled back to active) and the endpoint, but says nothing about permissions, idempotency, whether an already-active invoice errors, or what side effects reactivation has on reporting/numbering.

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 action and its effect; nothing redundant. The trailing HTTP method/path adds little for an agent choosing a tool, which keeps it just short of a 5.

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

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

For a two-parameter, schema-rich mutating tool with no output schema, the description is minimally sufficient: it identifies the resource and the state change. It omits failure modes and preconditions (non-cancelled invoice, missing series) that an agent would benefit from knowing before invoking.

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 two parameters (series_name, number) are fully documented in the schema. The description adds no extra syntax or format detail beyond what the schema already states, 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?

Specific verb (restore) plus resource (invoice) and the resulting state change (cancelled -> active again), so the agent knows exactly what happens. It does not, however, mention the closely-named sibling smartbill_restore_estimate, so the discrimination from that tool is left to 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 precondition phrase 'invoice that was cancelled', which tells the agent this only applies to cancelled invoices. There is no explicit when-not guidance, no mention of restore_estimate as the alternative, and no statement about what happens if the invoice is already active.

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

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

With only destructiveHint=true in the annotations, the description carries meaningful extra context: it takes the next number, is limited to one reversal per invoice, is irreversible, and may be transmitted to e-Factura/ANAF. These are exactly the mutation side-effects an agent needs before invoking a destructive operation.

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

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

Three dense sentences plus the endpoint, front-loaded with the action and its irreversible consequences. Every clause earns its place; nothing is padded.

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

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

For a 3-parameter mutation with no output schema, the description covers irreversibility, once-only semantics, and transmission behavior. Return/response details are not described, but no output schema exists to relieve that, so it is nearly complete rather than fully so.

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 three parameters are already documented, including issue_date's default and date constraint. The description reiterates the required series/number validation but adds no syntax or format beyond the schema, making the 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 gives a specific verb and resource: 'ISSUE a storno (credit) invoice that reverses an issued invoice.' That is far more precise than the name alone. It does not, however, explicitly distinguish itself from close siblings like smartbill_cancel_invoice or smartbill_restore_invoice, leaving the agent to infer the difference.

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 supplies concrete usage conditions: an invoice can be reversed only once, the storno cannot be undone, and it may be sent to e-Factura/ANAF. It also gives an operational instruction ('Confirm the exact series and number with the user first'). It stops short of naming when to prefer this over cancel/restore alternatives.

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

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

Adds substantial context beyond the destructiveHint=true annotation: it emails an external third party, is irreversible ('cannot be recalled'), falls back to the client's address and the account's template, and requires user confirmation. This is exactly the behavioral disclosure an agent needs before invoking an irreversible outbound action.

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

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

Four tight sentences, front-loaded with the action and its irreversibility, followed by defaults and the POST path. The endpoint reference mildly duplicates what an agent already infers from the tool call, but nothing is bloated.

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 an 8-parameter irreversible action with no output schema and only a destructiveHint annotation, the description supplies the precondition, defaults, safety warning, and confirmation requirement. It omits only error/rate-limit behavior and result reporting, which are secondary here.

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 baseline is 3. The description restates the fallback semantics for `to` and the template defaults for subject/body, which the schema already documents per-parameter; it adds no new syntax or format detail.

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

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

States a specific verb and resource ('Send an issued invoice or proforma by email') and constrains scope to already-issued documents. No sibling tool sends documents, so it is clearly distinguishable from the cancel/create/restore family.

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 default behavior when `to`, `subject`, and `body_text` are omitted, warns that the action cannot be recalled, and instructs the agent to confirm the recipient with the user first. It does not name any alternative tool, but no sibling performs a comparable send operation, so the guidance is effectively complete.

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