Számlázz.hu MCP by usefulapi

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

Annotations already declare readOnlyHint=true, and the description reinforces the safe-read nature while adding context the annotations cannot: the data originates from the NAV Online Invoice platform and the underlying Számla Agent action (action-szamla_agent_taxpayer). It does not cover failure behavior (does an unregistered number return a flag or an error?) or any rate limits.

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

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

Two sentences, front-loaded with the operation and its return fields before the implementation detail. The trailing mention of the Számla Agent action name is marginally useful for traceability but is the least essential 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 burden of describing returns — and it does, naming validity, name, VAT status and addresses. It still omits what happens for an unknown tax number and whether all four fields are always returned, which is the one remaining gap for a lookup tool.

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

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

Schema description coverage is 100% and the single parameter is fully documented (pattern ^\d{8}$, example given). The description adds only the Hungarian domain term 'törzsszám' for the same value, so it neither expands nor detracts from what the schema already carries — 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 ('look up') and resource (a Hungarian taxpayer in the NAV register), and enumerates what the caller gets back: validity, name, VAT status and addresses. No sibling tool does anything remotely similar (all others are invoice/receipt operations), so it is trivially distinguishable.

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

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

The description makes the input constraint clear ('by the first 8 digits of the tax number') and identifies the data source, which implies the validation use case, but it never states when to reach for this tool versus something else or what to do when a number is not found. Usage is inferable 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 only supply destructiveHint=true; the description goes well beyond that by disclosing NAV/Online Számla reporting, that the document can never be deleted but only reversed, that preview=true creates no document, and that the call is never retried. The warning that a returned invoice_number means a document WAS created is exactly the kind of side-effect detail an agent needs before re-issuing.

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 most critical fact (fiscal, irreversible) and packs kind semantics, preview behavior, retry policy and email behavior into a tight paragraph with no filler sentences. The trailing 'Számla Agent action-xmlagentxmlfile' is internal plumbing that adds little for an agent and slightly dilutes an otherwise sharp block.

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 31-parameter fiscal mutation with no output schema, the description covers the irreversible-action risk, the preview mode, idempotency/lookup strategy and email side effects, and even hints at the reply shape. It stops short of describing the full response (PDF availability, error codes other than the e-invoice one), which an agent must infer.

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 already 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: kind values are glossed (proforma = díjbekérő, non-fiscal, deletable; prepayment = előlegszámla), it states the tool computes net/VAT/gross from net_unit_price and vat_rate, and it explains what send_email_to_buyer actually does. It doesn't cover foreign-currency requirements despite the schema flagging them.

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 ('ISSUES a real invoice in Számlázz.hu') and immediately differentiates itself from siblings by naming szamlazz_reverse_invoice and szamlazz_delete_proforma as the only ways to undo the variants. An agent knows exactly what this does and which tools are its counterparts 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?

Explicitly routes between the three modes (invoice vs proforma vs prepayment) and names the sibling that handles deletion of a proforma. It also gives a clear operating rule for a failure case (never retried; look up via szamlazz_get_invoice by order_number or external_id) and tells the caller to always supply external_id/order_number so that lookup is possible.

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 flag destructiveHint=true, but the description goes far beyond: fiscal/NAV nature, irrevocability, cancel-not-delete semantics, call_id idempotency with the specific vendor error 338, and the no-auto-retry protocol. This is exactly the behavioral context the annotation cannot convey.

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

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

Front-loaded with the core action and the irrevocability warning, then layered with operational detail. Every sentence carries distinct information, though the density approaches the upper bound of what an invocation-time description should hold.

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, non-idempotent fiscal write with no output schema, the description covers safety profile, idempotency, error recovery, and prefix constraints. Nothing critical to correct invocation is left implicit.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: it explains how gross_total and vat_rate drive the derived net/VAT/unit price, clarifies that the prefix must be a receipt-only prefix, and states call_id's uniqueness requirement. It does not, however, elaborate on payment_method, order_number, or comment 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 precise verb and resource: 'ISSUES a real HUF receipt (nyugta)'. It explicitly differentiates itself from the invoice path ('must be a receipt-only prefix... not an invoice prefix') and from its cancellation sibling, so an agent can route correctly 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?

Names the alternative for cancellation (szamlazz_reverse_receipt) and gives explicit retry guidance (never auto-retry; repeat with the SAME call_id). Missing only an explicit statement of when to prefer this over szamlazz_create_invoice; the distinction is implied through the prefix rule rather than stated directly.

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; the description adds real value beyond that by scoping the blast radius ('only pro forma invoices can be deleted') and stating irreversibility ('Cannot be undone'), plus the underlying Számla Agent action for traceability. It stops short of covering auth requirements, not-found behavior, or what a successful call returns.

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

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

Three tight sentences, zero padding, and the destructive verb is front-loaded in capitals. Each clause (identifier rule, scope limit, irreversibility, routing) 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 two-param destructive tool with no output schema, the description covers the selector rule, the scope restriction, irreversibility, and the sibling to use instead. Only error/not-found semantics and confirmation of outcome are unaddressed, which is a minor gap given annotations already flag destructiveness.

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 the mutual-exclusion constraint ('give exactly one') that the schema does not express — both properties are merely optional strings with no oneOf. It also labels order_number vs invoice_number as alternative identifiers, though it adds no format guidance beyond the schema's example.

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 (DELETES) plus specific resource (one pro forma invoice / díjbekérő) and it names the domain term in both languages. It explicitly separates itself from szamlazz_reverse_invoice, so an agent can distinguish it from the closest sibling 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?

States the alternative and the condition that selects it ('a real invoice is never touched, use szamlazz_reverse_invoice'), plus the mutual-exclusion rule for the two selectors ('give exactly one'). Both when-to-use and when-not-to-use are covered explicitly.

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, and the description goes further by disclosing the exactly-one selector constraint, the 'last invoice wins' tie-break for order numbers, and the account-scoping limitation. No permissions or error behavior described, but the added context is substantive.

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 purpose, then constraints, then the secondary use case, with no filler. The long parenthetical is dense but every clause carries information; marginally less scannable than it could be.

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

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

With no output schema, the description usefully enumerates the returned field groups, and it covers identifier selection, scope, and a secondary purpose. It stops short of describing not-found/failure behavior, but an agent has enough 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?

Schema coverage is 100% with per-parameter descriptions, so the baseline is 3; the description adds that only one of the three identifiers may be supplied, a mutual-exclusion rule the schema itself does not express (all params optional, none required).

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

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

States a specific verb (read) and resource (one issued invoice), enumerates what is returned (seller, buyer, lines, totals, VAT breakdown, payments), and names the three lookup keys. It is clearly distinguishable from siblings like szamlazz_get_invoice_pdf or szamlazz_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 the selection rule ('give exactly one'), the multi-match behavior for order numbers (last one returned), the scope restriction (only invoices in this account), and an additional use case (existence check before re-issuing). Lacks an explicit named alternative tool for that re-issue check, but the guidance is otherwise concrete.

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 genuinely useful behavioral context by stating the return shape ('Returns the totals and the PDF as an embedded resource'), which matters because there is no output schema. It does not cover failure modes (e.g., document not found) or auth requirements.

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

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

Two compact sentences front-load the action, the scope and the identifier options, then disclose the return artifact. The trailing 'Számla Agent action-szamla_agent_pdf' is implementation detail that adds little for an agent, slightly diluting an otherwise tight entry.

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 three loosely-constrained parameters, no output schema and only readOnlyHint for annotations, the description supplies the missing pieces: which identifiers suffice and what comes back (totals plus an embedded PDF resource). Error behavior and any permission requirements remain unspecified, but nothing essential to a correct call is missing.

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

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

Schema coverage is 100% and each identifier is documented there, which sets a baseline of 3. The description goes beyond the schema by imposing a mutual-exclusivity rule ('give exactly one'), a constraint the schema does not encode (no oneOf, no required fields), and by clarifying that any of the three identifiers is acceptable.

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

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

The description uses a specific verb+resource ('Download the PDF of one issued document') and enumerates the acceptable identifiers, so the agent knows exactly what it retrieves. It does not explicitly contrast itself with the sibling szamlazz_get_invoice (data vs PDF), so sibling differentiation is only implied.

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?

'(give exactly one)' conveys an invocation constraint, and the identifier list implies when the tool applies, but there is no explicit when-to-use guidance or routing to alternatives such as szamlazz_get_invoice for non-PDF retrieval. 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?

readOnlyHint=true already covers the safety profile, so the description's added value is the enumeration of what comes back (lines, payments, totals, reversal status) and that the PDF is optional. It does not disclose failure behavior for an unknown receipt number, which would be useful for a pure lookup 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?

Two tight sentences with the lookup key and returned fields front-loaded, no filler. The trailing internal action string 'Számla Agent action-szamla_agent_nyugta_get' adds little for an agent choosing 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?

With no output schema, the description usefully enumerates the returned fields, which is the key missing piece an agent needs. A two-parameter read tool is otherwise well covered; only error/edge behavior (nonexistent receipt number) is 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%, with both parameters fully documented, so the baseline is 3. The description's 'by receipt number' and 'Optionally the PDF' merely restate the schema and add no format or syntax detail beyond it.

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

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

States a specific verb (read) and resource (one issued receipt/nyugta) plus the lookup key (receipt number) and enumerates the returned content. The receipt-vs-invoice resource distinction implicitly separates it from szamlazz_get_invoice, but no sibling is named explicitly, so the split with szamlazz_get_invoice_pdf or szamlazz_reverse_receipt 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?

'Read one issued receipt by receipt number' implies the fetch-a-known-receipt use case, and 'Optionally the PDF' signals the pdf flag's role. There is no explicit when-to-use/when-not guidance and no routing to alternatives such as szamlazz_get_invoice_pdf or the create/reverse receipt siblings.

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

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

Annotations only declare destructiveHint=true; the description clarifies that this is destructive only under replace_existing, which REPLACES all earlier payment entries, while the default is additive. It also flags the operation as 'Not fiscal' and describes the balance mutation. Return shape is not covered, 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 tightly packed sentences with zero filler; the core action and target lead, the add-vs-replace contract follows immediately, and the non-fiscal caveat closes. 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?

With no output schema, the description compensates by stating the effect on paid amount and outstanding balance and the replace contract, which is what an agent needs. Only the response/confirmation format and any permission requirements 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?

Schema description coverage is 100%, so all four parameters are already documented in the schema, including currency rounding behavior and replace_existing semantics. The description restates the add/replace behavior but adds no format or syntax detail beyond the structured fields, 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 (Records) and resource (1-5 payments) on a precisely scoped target (your own issued invoices or pro forma invoices), and names the downstream effect (updates paid amount and outstanding balance). No sibling handles payments, so it is cleanly distinguishable from get_invoice / reverse_invoice / 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?

The scope constraint ('one of your own issued invoices or pro forma invoices') tells the agent when this applies, and the add-vs-replace boundary is spelled out. It lacks an explicit 'when not to use / use X instead' statement, but no sibling overlaps the payments domain, so less routing guidance is needed than a crowded namespace.

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 provide destructiveHint=true; the description goes well beyond that by disclosing that the reversal is reported to NAV, cannot be undone, leaves the original in the books, and must not be retried. These are consequential traits not derivable from the structured fields.

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

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

Front-loads the core action and fiscal consequence, then the prerequisite, then the retry policy; every sentence carries information. Minor redundancy in the title/description overlap and the trailing internal action tag, but nothing wasteful enough to penalize heavily.

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 irreversible fiscal mutation with no output schema, the description covers consequences, prerequisites, and a verification path. It stops short of saying what the response contains (e.g. the new reversal invoice number), which would help an agent confirm success.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a real constraint beyond the schema: the invoice_number must belong to a real/issued invoice, not an arbitrary string. The other parameters (reason, e_invoice, issue_date) are left to the schema.

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

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

States a specific verb (ISSUES a reversal/storno invoice) and the exact resource/effect (cancels one issued invoice, original stays in the books). It is easily separable from siblings like szamlazz_create_invoice, szamlazz_delete_proforma, and szamlazz_reverse_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?

Explicitly conditions use (requires the number of a real invoice) and gives a when-not/alternative path: never retry, and verify with szamlazz_get_invoice when the result is unclear. This is exactly the kind of routing an agent needs for an irreversible fiscal operation.

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

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

Annotations only declare destructiveHint=true; the description adds critical behavior: fiscal and irreversible, one reversal per receipt, a reversal cannot itself be reversed, and a no-retry protocol with get_receipt as recovery. This goes well beyond the annotation.

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 and dense: the first two sentences carry purpose and irreversibility, and the third carries the no-retry recovery. The final Számla Agent action tag is an implementation identifier that is useful for logs but not required for selection or invocation, so the description is slightly less lean than it could be.

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

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

For a high-stakes fiscal mutation with no output schema, the description supplies the essential operational constraints: one-time, irreversible, and don't retry blindly. It does not describe the successful return shape or any auth/permission requirements, but the get_receipt fallback mitigates the main uncertainty.

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 receipt_number and call_id are fully documented in the schema. The description does not add syntax, format, or selection guidance for either parameter beyond implying a single issued receipt.

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

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

States a precise verb and resource: ISSUES a reversal (storno) receipt that cancels one issued receipt. It distinguishes this from create_receipt/get_receipt and from reverse_invoice by naming receipt reversal and its fiscal nature.

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

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

Gives explicit conditions: use to cancel one issued receipt, only once, and never retry an unclear result without first checking szamlazz_get_receipt. It names the alternative tool for resolving ambiguity, so the when and when-not are both covered.

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

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

The description adds real behavior beyond destructiveHint=true: 'The e-mail cannot be recalled' flags irreversibility, and the omitted-fields fallback explains a non-obvious side effect (re-sending with prior settings). It does not cover auth/permission needs or rate limits, but for a send action the key behavioral risk is disclosed and consistent with the annotation.

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

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

Three sentences, each earning its place: the core action first, then the optional-parameter behavior, then the irreversibility warning, with the internal action name appended. Tightly front-loaded with zero filler.

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

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

With no output schema and only one required parameter, the description covers the action, the fallback behavior, and the irreversibility warning. It leaves minor gaps such as whether the receipt must exist in the account and what a success response looks like, but nothing 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%, so the baseline is 3, but the description adds meaning the schema lacks: that omitting email/subject/body/reply_to is not an error but triggers a re-send using the previous e-mail's configuration. That is a semantic behavior of the optional parameters documented nowhere in the schema.

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

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

States a specific verb and resource ('E-MAILS an already issued receipt (PDF) to a customer'), including the scope qualifier 'already issued' and the underlying Számla Agent action name. It is clearly distinguishable from siblings such as szamlazz_get_receipt, szamlazz_create_receipt, and szamlazz_reverse_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?

Gives a clear operational condition: supplying no e-mail fields causes the vendor to re-send using the earlier e-mail's settings, and states the prerequisite that the receipt is already issued. It does not name alternative tools or explicitly state when not to use it, but the usage context is unambiguous.

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