A-Cube MCP by usefulapi

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

Annotations already declare idempotentHint=false and destructiveHint=false, but the description converts that into an actionable consequence: calling twice creates two drafts. It also clarifies the draft is inert until sent, which goes beyond the annotation set. It omits permissions/auth requirements and error behavior, so 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?

Four short sentences, front-loaded with the WRITE marker, each carrying distinct information (draft semantics, non-idempotency, validation prerequisite, 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?

Covers the mutation semantics, duplication risk, and pipeline position for a nested-body tool with no annotations gap. The remaining gap is the return shape: with no output schema, the description never says the response yields the draft identifier an agent would need for acube_send_draft_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% and the nested field guidance (dati_generali, dati_beni_servizi, full header with seller and buyer) lives in the schema itself. The description adds no parameter-level detail beyond naming the endpoint, 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?

Opens with a specific verb and resource plus scope: 'WRITE: saves a new invoice as a DRAFT in A-Cube.' It also distinguishes itself from the send path by name (acube_send_draft_invoice), so an agent can tell create-draft from send-draft without opening either schema.

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

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

Explicit sequencing: validate first with acube_validate_invoice, nothing reaches the SDI until acube_send_draft_invoice. It names the prerequisite and the follow-up tool, which is exactly the when/when-next guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'permanently deletes' is reinforcement rather than new info. The real added value is the safety-gate behavior: without confirm:true the call degrades to a preview, and a sent invoice yields 409 — both are behavioral traits not expressible in annotations.

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

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

Three tightly packed clauses: WRITE marker, scope constraint, safety gate, then endpoint. Front-loads the destructive nature and 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?

Covers mutation semantics, the draft-only restriction, the confirm gate, and the error case, which is enough for a 2-parameter tool with no output schema. It omits permission/auth requirements, but nothing else an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline of 3 applies. The description's note about confirm:true largely restates the schema's own description of that 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 and resource ('permanently deletes a draft invoice') plus the exact endpoint DELETE /invoices/draft/{uuid}. The draft-only scope cleanly separates it from siblings like acube_send_draft_invoice or acube_get_draft_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 'draft only: a sent invoice answers 409' clause tells the agent the precondition and the alternative outcome for non-draft invoices. It stops short of naming the sibling to use for other invoice lifecycles, but the applicability boundary 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by enumerating what the payload contains (name, email, enabled services, webhook configurations) and pinning it to a concrete endpoint, which matters because there is no output schema. It stops short of disclosing error/not-found 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 short sentences, front-loaded with the resource and the returned content. The trailing endpoint is arguably redundant for an agent but does anchor the tool to a known API surface, so it earns a marginal 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 one-parameter read with no output schema, the description supplies the key missing piece: the shape of the returned business configuration. Only the failure mode (invalid or unknown fiscal id) and any pagination-free assumptions are left unstated.

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 a single parameter at 100% schema description coverage, the schema already explains that fiscal_id accepts a codice fiscale or partita IVA. The description only restates "by fiscal id" and adds no format, normalization, or validation detail 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?

"One business by fiscal id" plus the returned fields (name, email, enabled services, webhook configurations) and the REST endpoint make the resource and scope unambiguous. It implicitly separates itself from acube_list_business_registry_configurations by returning a single business, but never names that sibling 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?

The singular framing ("One business by fiscal id") hints that this is the lookup path when you already know the fiscal id, versus the list sibling. There is no explicit when-to-use statement, no prerequisite, and no stated behavior when the id is unknown.

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. The description adds meaningful behavioral context by clarifying that the returned number is the last used number, not the next available number, which prevents a likely off-by-one misuse.

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 short and front-loads the important semantic about the returned number. The raw endpoint string is somewhat technical but helps map the tool to the underlying API, and no sentence is wasted.

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

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

For a simple read-only tool with one required parameter and no output schema, the description covers the core purpose and the most important return-value semantics. It could do slightly more to explain error behavior for unknown sequence names, but it is largely 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 parameter 'name' already has a description. The description mentions 'sequence name' and mirrors the endpoint path, but it does not add format details, examples, or constraints beyond what the schema provides.

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

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

The description states clearly that it retrieves the active numbering sequence for a given sequence name and explains the key semantic of the returned number: it is the last used number, so the next invoice gets that number plus one. It does not explicitly contrast with the sibling acube_list_numbering_sequences, which keeps it from a 5.

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

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

Usage is implied by the explanation that the next invoice gets the returned number plus one, which suggests the tool is useful for determining the next invoice number. However, it does not explicitly say when to use this instead of acube_list_numbering_sequences or what happens if the sequence name does not exist.

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

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

The annotations already declare that this is a read-only, non-destructive, open-world operation, so the description does not need to establish safety. It adds useful context by stating that the response includes FatturaPA JSON content and by naming the underlying GET endpoint, but it does not describe error behavior, permissions, or response shape in more detail.

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 clauses with no wasted wording, and the core resource plus lookup key is front-loaded. The endpoint reference is supplementary but still brief.

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 tool with complete schema coverage and annotations covering safety, the description is largely complete. It notes the returned FatturaPA JSON content, which matters because no output schema is provided, though it could mention error behavior or the origin of the uuid.

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 single uuid parameter is already fully documented in the input schema. The description repeats that lookup is by uuid but adds no format, source, or validation detail 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 states a specific verb and resource: retrieve one draft invoice by uuid, including its FatturaPA JSON content. It distinguishes draft invoices from the sibling get_invoice by naming the draft resource, but it does not explicitly contrast the two alternatives.

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

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

The phrase 'by uuid' implies this tool is for direct lookup when the caller already has a draft invoice identifier. However, it does not explicitly say when to use this instead of acube_list_draft_invoices or acube_get_invoice, nor does it mention prerequisites such as obtaining the uuid first.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing what each mode returns (metadata + structured FatturaPA fields vs. the raw XML transmitted to the SDI), which matters given there is no output schema. It omits error behavior, e.g. what happens for an unknown uuid or one not yet sent.

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 payload description front-loaded and the REST endpoint trailered for agents that map to the API surface. No filler, nothing repeated from the annotations.

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 read tool with full annotation coverage and an optional xml mode, the description supplies everything needed to call it correctly, including the meaning of both output shapes. It stops short of covering failure modes or confirming that metadata is included in xml mode, which would close the 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?

Schema coverage is 100% and already documents uuid, format, and the json default, so the baseline is 3. The description earns above baseline by explaining what each format value actually yields – parsed FatturaPA JSON versus the original SDI XML – which the enum alone does not convey.

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

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

States a specific verb and resource ('One invoice by uuid') and goes further to name what comes back: metadata plus the FatturaPA JSON payload, or the XML sent to the SDI. It does not explicitly distinguish itself from the adjacent acube_get_draft_invoice sibling, 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?

Usage is only implied: retrieve a single invoice when you have a uuid. There is no explicit when-to-use guidance, no statement of when to prefer acube_get_draft_invoice or the list endpoints, and no mention of format selection heuristics. The 'uuid (from acube_list_invoices)' hint lives in the schema, not the description.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description nonetheless adds genuinely non-obvious behavior: results are annual by default, with monthly or daily detail only if A-Cube has activated it. It does not explain what happens for years outside the 2000-2100 range or how empty/unauthorized cases 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 that front-loads the resource and the key scoping caveat, followed by the endpoint path. Nothing is wasted, though the raw 'GET /invoices/stats/{year}' is marginal value for an MCP caller.

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 only two parameters and no output schema, the description should hint at the shape of the returned counters (which counts, by status or period). It says 'counters of invoices and notifications' but leaves the response structure largely unspecified, so an agent knows the intent but not what it will receive.

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 and the baseline is 3. The description adds only a modest clarification that omitting fiscal_id aggregates the whole account rather than a single customer, which is useful but thin.

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

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

States a specific resource ('counters of invoices and notifications') scoped to a year and optionally a fiscal id, which is clearly distinct from the list_* siblings that return individual records. It does not name any sibling explicitly, but the aggregate-vs-list distinction is inferable from the wording.

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 (getting aggregate counts for a year) but never states when to prefer this over acube_list_invoices or acube_list_invoice_notifications, nor any exclusions. An agent must infer that this is the summary path rather than the detail path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the response carries status and result, but says nothing about whether statuses are terminal, whether the call must be repeated until completion, or what happens for an unknown uuid.

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 and its return payload; no filler. The trailing REST path is marginal value but not wasteful for agents mapping to the underlying API.

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 no output schema and no dedicated behavioral notes, the description does carry the return contract at a high level ('status and result'), which is the minimum needed. It stops short of the details that matter for a job-polling tool, such as status values or completion semantics.

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 a single parameter at 100% schema description coverage, the schema already fully documents uuid including its source. The description's 'by uuid' only echoes that, adding no format or constraint detail 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 resource (a single background job) retrieved by uuid and what it returns (status and result), which distinguishes it from the sibling acube_list_jobs. The verb is implicit in the 'by uuid' phrasing and the GET path rather than stated outright.

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?

Retrieval-by-identifier usage is implied clearly enough, and the schema notes the uuid comes from acube_list_jobs. However, the description itself never names that alternative or says when to use this versus listing jobs, nor does it mention polling after a job is created.

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 one useful behavioral detail — that the response includes the notification payload — but says nothing about not-found behavior, error modes, or payload shape.

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 the core operation front-loaded and zero filler. The endpoint reference is a small but useful anchor for agents familiar with the HTTP API.

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?

This is a single-parameter read tool with full annotation coverage and full schema documentation, and the description discloses that the payload is returned. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and the uuid parameter is fully documented there including its provenance from acube_list_invoice_notifications. The description only restates 'by uuid' and adds no format or constraint detail beyond the schema's minLength/maxLength, 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 states a specific verb and resource ('One SDI notification by uuid') and adds scope detail ('with its payload', 'GET /notifications/{uuid}'). The singular 'one ... by uuid' implicitly distinguishes it from the sibling acube_list_invoice_notifications, 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?

Usage is only implied: the agent must already have a uuid to call this, and the schema note points to acube_list_invoice_notifications as the source. The description itself gives no explicit when-to-use or when-to-prefer-the-list-tool 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description contributes beyond that by disclosing the response shape (fields and cross-links to voiding/returned receipts) and the underlying endpoint GET /receipts/{uuid}. It stops short of noting pagination, auth, or error behavior, keeping it below 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?

A single front-loaded sentence does the work: the resource leads, the returned fields follow, then the sibling routing, then the endpoint. The colon-list style is slightly telegraphic and the trailing REST path is marginal, but nothing is wasted or 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?

With no output schema, the description carries the burden of describing returns, and it does so by naming the fields and the linked voiding/returned receipts. For a one-parameter read tool with full annotation coverage, an agent has everything needed to call it correctly.

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

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

With one parameter at 100% schema description coverage, the schema already tells the agent the uuid comes from acube_list_receipts. The description only restates 'by uuid' and adds no format or constraint detail beyond the schema's 1-120 character bounds, 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?

Specific verb-plus-resource ('one electronic receipt by uuid') with an enumeration of exactly what comes back: type, status, number, date, total, and voiding/returned links. It also carves itself apart from acube_get_receipt_details by naming the missing payload (line items), so the agent can distinguish the two without opening either schema.

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

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

The parenthetical '(no line items: use acube_get_receipt_details)' names the alternative explicitly and states the condition that selects it. That is the same routing pattern as the high-quality calibration example, and nothing about when to pick this tool is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered without the description's help. The description earns some credit by naming the fields returned (line items, VAT, discount, taxable totals), which matters because there is no output schema, but it says nothing about not-found behavior or how the payload differs from acube_get_receipt.

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 with the returned payload front-loaded before the endpoint reference; nothing is padded. It could have spent one of those sentences on sibling differentiation instead of repeating the route, but it is efficiently structured.

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 one-parameter read tool, the description gives a reasonable sketch of the return content in lieu of an output schema. The material omission is the relationship to acube_get_receipt, which a 'details' variant of the same resource should really explain.

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

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

There is a single uuid parameter with 100% schema description coverage, and the schema already tells the agent to source it from acube_list_receipts. The description adds no format, length, or sourcing detail beyond that, so baseline 3 applies.

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

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

The description states a specific payload verb+resource: it returns line items and VAT/discount/taxable totals for one receipt, plus the underlying route GET /receipts/{uuid}/details. It is clear on its own, but it never distinguishes itself from the sibling acube_get_receipt, leaving an agent to guess which receipt endpoint returns which shape.

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 use this versus acube_get_receipt or a receipt list call. The only workflow hint lives in the schema ('from acube_list_receipts'), not the description, and no exclusions or prerequisites are given.

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

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 useful domain context (7-character format, it is the code customers write on invoices to you) and the underlying endpoint, but does not say what happens if the code is not configured or whether it is cached/rate-limited.

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 clauses with zero filler, front-loading the returned value and then the endpoint. Minor weakness: it is a fragment with no verb, and the raw GET path adds little for an agent that cannot call HTTP directly.

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

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

With no output schema, the description carries the return-value burden and does so adequately by specifying a 7-character code string. The only real gap is edge-case behavior when no recipient code has been configured.

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?

Zero parameters, so the baseline is 4; there are no argument semantics to explain. The description correctly makes no parameter claims and instead spends its words on what is returned.

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 exact resource returned (the account's 7-character SDI recipient code / codice destinatario) and adds a plain-language gloss of what it is. It is a noun phrase rather than a verb+resource statement, but the retrieve semantics are unambiguous and no sibling returns this 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?

Usage is only implied: the agent can infer this is the tool to call when it needs the invoice recipient code, e.g. before creating a draft invoice. There is no explicit when-to-use, no mention of prerequisites (SDI/Italian account), and no routing against near siblings like acube_get_business_registry_configuration.

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 per-service enablement flags, which is useful return-content context, but says nothing about pagination behavior or result ordering. 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 front-loaded sentence that leads with the resource and its returned fields, then the endpoint. Slightly awkward phrasing ('with which services are on') but no waste.

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 seven optional filter parameters, the description should at minimum signal that the tool is filterable and paginated. It covers the resource and returned service flags but leaves filtering and paging strategy to the schema, which is adequate but thin for a list tool of this 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%, so all seven parameters are already documented in the schema, including the partial-match and exact-match semantics of name and fiscal_id and the paging hint. The description adds no filtering syntax or semantics 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?

The description names the resource (businesses / fiscal ids on the account) and enumerates the service flags returned (customer invoices, supplier invoices, receipts, signature, legal storage), plus the underlying endpoint. It is clearly a list operation and reads distinctly from acube_get_business_registry_configuration, though it never states the list-vs-single relationship 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?

There is no guidance on when to call this versus acube_get_business_registry_configuration or acube_verify_fiscal_id, and no mention that the tool supports filtering by name, email, fiscal id, or service flags — even though seven such parameters exist. The agent must discover all selection logic from the schema alone.

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 real domain context by defining the returned set as invoices 'created but not yet sent to the SDI' and citing the underlying endpoint GET /invoices/draft. It says nothing about result size, ordering, or pagination behavior beyond what the schema already documents.

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 fragments, front-loaded with the defining state of the resource before the cross-reference and endpoint. Nothing is wasted. Slightly clipped prose (no explicit verb) and the reliance on another tool's documentation keep 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 zero-required-parameter read-only list tool with a fully documented schema and annotations, the description covers the essentials. What it omits is what SDI means for an unfamiliar agent and any note on how the draft set is scoped or ordered — minor, but the description leans on the sibling for filter semantics.

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% — every one of the six filter parameters has its own description, defaults, bounds, and format patterns. The description adds only a cross-reference ('same filters as acube_list_invoices'), which helps an agent transfer expectations but conveys no new per-parameter meaning. Baseline 3 is appropriate.

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

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

The description names the exact resource and its distinguishing state: draft invoices created but not yet sent to the SDI. That cleanly separates it from acube_list_invoices (sent) and acube_get_draft_invoice (single record). The verb 'list' comes from the name/title rather than the prose, so it falls just short of a fully self-contained 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?

'Same filters as acube_list_invoices' implies this is the draft-state counterpart to that listing, which is useful context. But it never explicitly says when to pick this over acube_list_invoices or acube_get_draft_invoice, nor any prerequisites (e.g., that drafts are pre-SDI-submission only). Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile needs no restating. The description adds the underlying endpoint (GET /invoices/{uuid}/notifications), which is useful context, but is silent on edge behavior such as whether an invoice with no notifications returns an empty list, and on pagination 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 front-loaded sentence plus the endpoint path — every element earns its place, with the notification-code enumeration doing real disambiguation work. Slightly dense in the parenthetical list, but 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 list with no output schema, the description usefully previews the shape of each record (type, date, status), which is what an agent most needs to interpret results. Only the empty-result and pagination behavior are left unaddressed.

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

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

There is a single parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds no format, sourcing or lookup guidance for the uuid 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 ('SDI notifications of one invoice'), enumerates the notification codes (RC, NS, NE, MC, DT) so the agent knows exactly what is returned, and frames the business purpose ('how you tell whether an invoice was delivered or rejected'). This clearly separates it from acube_get_notification (singular) and acube_get_receipt.

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 clause 'how you tell whether an invoice was delivered or rejected' gives an unambiguous use case, so an agent knows when to reach for this tool. It stops short of naming alternatives or exclusions (e.g. use acube_get_notification for a single notification), leaving that inference to the agent.

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

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 account scope and the returned field set, but nothing about pagination limits, result ordering defaults, or rate behavior — a modest lift beyond the annotations rather than a rich one.

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 dense sentences plus the endpoint, with the resource and returned fields front-loaded before the filtering clause. Nothing is redundant, though the field enumeration is long enough that it borders on a schema restatement.

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 16 optional parameters and no output schema, the description usefully names the returned fields (uuid, number, date, document type, parties, amounts, marking/notification status) so the agent knows what a call yields. The only gap is absence of any note on pagination behavior or empty-result semantics, which is partly covered by the items_per_page schema text.

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 16 parameters are fully documented in the schema (defaults, enums, patterns, partial-vs-exact match semantics). The description only restates the filter categories at a higher level and adds no syntax or semantics beyond the schema, which is the correct baseline for a fully covered schema.

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

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

Opens with a specific verb+resource ('Sent and received Italian e-invoices (SDI) of the account') and enumerates the fields returned, so the agent knows exactly what comes back. It implicitly separates itself from acube_list_draft_invoices and acube_get_invoice, 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?

The filter list ('Filter by date, number, document type, party name or VAT number') signals when the tool is applicable, but there is no explicit guidance on when to prefer this over acube_list_draft_invoices, acube_get_invoice, or acube_get_invoice_stats.

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 the scope of job types and statuses but does not describe pagination behavior or the structure of returned jobs.

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

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

The description is compact and front-loads the resource and relevant job categories. However, it is phrased as a noun phrase rather than a clear action statement, which slightly reduces immediate readability.

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 listing tool with five optional parameters and full schema coverage, the description is adequate but thin. It does not mention the sibling single-job tool or describe the returned job list, which would help an agent use it confidently.

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 five parameters, including enums and pagination. The description lists job types and statuses that map to enum values but adds no syntax or filtering 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 identifies the resource clearly: background jobs, with concrete examples of job types and statuses, plus the GET /jobs endpoint. It does not explicitly distinguish this listing operation from the sibling acube_get_job tool, which is a minor clarity gap.

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 acube_get_job, nor any stated preconditions or exclusions. Usage is only inferable from the name and endpoint.

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 safety is covered. The description adds that results expose name, year and last number, which is genuinely useful given there is no output schema, but says nothing about pagination behavior or result volume 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?

Two short fragments with zero padding, and the resource plus returned fields are front-loaded. The raw 'GET /numbering-sequences' is marginal filler for an agent that never sees HTTP transport, but it is harmless and brief.

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 4-parameter read-only list tool with no output schema, the description covers the resource and returned fields, and pagination is handled by the schema. However it omits any hint about how to page through results or how this relates to the single-sequence sibling, leaving a modest 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?

Schema description coverage is 100%, so page, year, sequence_name and items_per_page are already documented with constraints and defaults in the schema. The description adds no extra semantics such as filter combination behavior, 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 specific resource (invoice numbering sequences) and even the fields it returns (name, year, last number), which is more concrete than the title alone. It does not distinguish itself from the sibling acube_get_current_numbering_sequence, leaving ambiguity about plural-list vs single-item retrieval, 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?

There is no guidance on when to call this instead of acube_get_current_numbering_sequence, nor any mention of the optional year/sequence_name filters being useful for narrowing results. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds nothing beyond that — no note on pagination semantics, result ordering, empty result behavior, or external-system dependency — so it carries little extra behavioral weight.

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, resource first, endpoint last — front-loaded and free of filler. It is terse rather than padded, though the terseness leaves coverage gaps rather than being a model of 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?

With 8 optional filters and no output schema, the description does supply the returned field list (number, date, status, type, totals), which partially compensates for the missing output schema. However it omits routing to acube_get_receipt_details for line-level detail and says nothing about how filters combine, leaving gaps for a listing tool with this many 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%, with every parameter documented including pagination defaults and the 'full page means there may be more' hint. The description adds no filter semantics of its own, so the baseline 3 applies.

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

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

The description names the resource (electronic commercial receipts / scontrini), the fields returned (number, date, status, type, totals) and the underlying endpoint GET /receipts, which together make the read/list purpose unambiguous. It does not distinguish this from sibling acube_get_receipt or acube_get_receipt_details, so an agent must infer the listing vs. single-record split from names 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?

There is no explicit statement of when to use this tool versus the sibling receipt tools, nor any prerequisite, exclusion or filtering advice. The only usage signal is the implicit 'GET /receipts' listing.

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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the returned payload shape (events and target URLs) and the explicit security guarantee that authentication keys and tokens are never returned — an important disclosure for an agent deciding whether this tool can answer a credential-related question.

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 path, front-loaded with the payload description before the security note. No wasted phrasing; the only marginal element is the raw endpoint path, which is mildly useful context rather than noise.

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

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

With no output schema, the description does the necessary work of saying which fields come back and what is withheld, and the three optional parameters are fully covered by the schema. Pagination semantics are handled in the schema's items_per_page note, so 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 page, fiscal_id and items_per_page are already documented including defaults and the max of 30. The description adds nothing on parameters beyond implying account scoping, which makes the schema baseline of 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 names the specific resource (webhooks) and enumerates what is returned: events and target URLs, scoped to the account. It lacks an explicit verb like 'List', but the resource and scope are unambiguous and no sibling tool overlaps (no other webhook-related tool exists).

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, no prerequisite or permission context, and no guidance on iterating pages even though the tool is paginated. Usage is only inferable from the read-only listing nature of the 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?

Despite annotations already flagging destructiveHint=true and idempotentHint=false, the description adds critical domain context: this is a legal act, the invoice cannot be recalled (only corrected via credit note), and it may be billed. It does not cover rate limits or error/response behavior, which keeps it just 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?

Four short sentences, front-loaded with the WRITE marker and the legal warning. Every sentence earns its place: purpose, irreversibility, billing consequence, confirm semantics, and call-to-action.

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, high-stakes mutation tool with no output schema, the definition supplies everything an agent needs: what it does, what is destroyed, what the safe preview path is, and the required user-confirmation step. No material gap remains.

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 (uuid, confirm) are already fully documented, including the preview behavior of confirm=false. The description restates the confirm semantics rather than adding new meaning, so the baseline of 3 applies.

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

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

States a specific verb (transmit/send), the exact resource (draft invoice), and the destination system (Sistema di Interscambio). The 'WRITE:' prefix and the endpoint POST /invoices/draft/{uuid}/send make it immediately distinguishable from create_draft_invoice, get_draft_invoice, and delete_draft_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?

Explicitly prescribes the workflow: show the draft to the user, get their explicit OK, then send with confirm: true. It also states what happens without confirm (preview-only return), so the agent knows the safe dry-run path and the irreversible path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true; the description adds useful confirmation that nothing is persisted or transmitted and notes the two possible outcome classes (validation result vs. A-Cube's errors). It stops short of saying whether validation is purely local/remote or what an error payload looks like, but it discharges the behavioral burden well for a read-only 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?

One front-loaded sentence carrying the action, the side-effect guarantee, and the return classes, plus a short endpoint tag. 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 validation tool with a fully described two-parameter schema and no output schema, the description covers the important ground. The remaining gap is that the "validation result" return shape is not characterized at all (valid/invalid flag vs. list of rule violations), which matters since no output schema exists to fill that in.

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 (including the nested FatturaPA body and header structures) are already well documented in the schema. The description adds nothing about parameters, so the baseline 3 applies.

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

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

Specific verb + resource ("Checks an invoice against the FatturaPA rules") with an explicit non-effect clause ("without creating or sending anything") that separates it from acube_create_draft_invoice and acube_send_draft_invoice. The endpoint reference (POST /invoices/validate) reinforces the read-only validation scope.

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 "without creating or sending anything" phrasing implies this is a pre-flight check rather than a substitute for creating or sending, so usage is inferable. But there is no explicit when-to-use guidance naming acube_create_draft_invoice or acube_send_draft_invoice as the follow-up steps, and no statement of prerequisites (e.g. what a "missing field" result means for the next call).

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 what data is returned and the opt-in split-payment check, but says nothing about behavior on unknown VAT numbers, error shapes, or whether the lookup is live registry data.

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

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

A single front-loaded sentence covering purpose, inputs and returned fields. The trailing HTTP route restates implementation detail that adds little for an agent, a small piece of non-earning 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?

There is no output schema, so the description carries the return-value burden and does so by naming the fields and the conditional split-payment result. Error/not-found behavior and data freshness remain undocumented, which is the main gap for a two-parameter lookup.

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 in-schema, so the baseline is 3. The description reinforces that 'id' is a VAT number and that check_split_payment is an additional check rather than a filter, but adds no format or validation detail 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 (look up / return registry data) and a specific resource (an Italian company identified by VAT number), and enumerates the returned fields (name, address, status). It does not explicitly contrast with the closely-named sibling acube_verify_fiscal_id, so sibling differentiation is left to inference.

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 'by VAT number' phrasing implies when to use it and the optional split-payment check is framed as opt-in, but there is no explicit when-to-use/when-not guidance and no routing away from acube_verify_fiscal_id or acube_get_recipient_code.

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 the HTTP endpoint (GET /verify/fiscal-id/{id}), hinting at a remote lookup, but it does not say what a response contains (a boolean? error details? company data for a partita IVA?) or handle rate/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 short sentences, zero filler, with the purpose front-loaded ahead of the endpoint detail. Nothing to trim.

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 should explain the return shape (validity flag, error semantics for malformed ids, whether extra info such as company name comes back for a partita IVA). That gap leaves an agent unsure what to expect from a verification call.

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

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

Schema coverage is 100% and the single `id` parameter already carries an example and a length constraint. The description's only added value is naming the accepted domains (codice fiscale vs partita IVA), which is modest given the schema 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 (checks) and resource (codice fiscale / partita IVA validity), which distinguishes it from sibling tools like acube_verify_company or acube_get_recipient_code. It does not explicitly name an alternative, so it falls just short of 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: an agent can infer this is for validating an id before using it elsewhere. There is no explicit when-to-use/when-not-to-use guidance and no routing to alternatives such as acube_verify_company.

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