Stackin

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

Goes well beyond the annotations (destructiveHint, idempotentHint, readOnlyHint) by detailing the fiscal/accounting impact, the verbatim submission of reason to the tax authority, and the exact semantics of idempotency_key (replay first answer vs. genuinely new cancellations). This is critical behavioral context not visible from structured 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?

The description is only four compact sentences (or a few short paragraphs), each carrying tactical value: the core action, legal conditions, human-in-the-loop rule, reason constraint, and idempotency behavior. No filler, fluff, or redundant restatements.

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

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

Given the tool's complexity and destructive nature, the description covers all non-obvious aspects the agent needs: the legal cancellation window, the requirement to ask the human, the verbatim reason, and high-value idempotency semantics. Since an output schema exists, return values are already documented and don't need describing.

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 0%, so the description must compensate. It provides important meaning for two parameters (reason min length and verbatim transfer; idempotency_key retry behavior). Access_key and document_type are left to inference, but document_type's enum is self-explanatory and access_key is predictably the invoice identifier, so the description handles the most nuanced parts.

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

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

States the action clearly ('Cancel an authorized invoice') and grounds it in legal/fiscal/accounting effect within the NFS-e municipality window, which distinguishes it from siblings like correct_invoice or invalidate_numbering.

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

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

Explicitly says to ask a human to confirm and never to call it speculatively, giving a clear when-to-use condition. It does not name sibling alternatives for when-not-to (e.g., 'use correct_invoice for adjustments'), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it never changes the document, which is redundant but consistent. It doesn't disclose any additional behaviors like error conditions or rate limits, but with annotations covering the safety, a score of 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?

Two sentences with no filler. The key information (read-only) is front-loaded. Perfectly concise.

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

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

The tool has an output schema, so return values are covered. However, the parameters are insufficiently explained: 'document_type' is required but its purpose is not stated. Given the low schema coverage, the description fails to make the tool callable 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?

The description mentions 'access key' but does not explain the purpose of 'document_type' which is a required enum (nfse, nfe). With 0% schema description coverage, the description should have explained both parameters, but it only covers access key, and even that is not elaborated beyond naming 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?

The description states a clear verb ('look up') and resource ('invoice's current status') with a specific access key. It is distinct from sibling tools like cancel_invoice or issue_invoice by being read-only.

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

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

The description explicitly says 'Read-only: it never changes the document,' which signals that this tool is for status checks only and not for modifications. However, it does not explicitly mention alternative tools, so it's slightly less explicit than ideal.

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

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

Annotations already declare destructiveHint=true, so the mutation aspect is covered. The description adds significant behavioral context: each letter supersedes the previous one, SEFAZ keeps at most 20 per document, and the text reaches the tax authority verbatim. It also explains the limitation on fiscal fields, which is not evident from annotations. This goes well beyond what annotations provide.

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

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

The description is concise and front-loaded with the core purpose, followed by essential limitations and side effects. Each sentence adds value, and it avoids redundant phrasing. It is slightly longer than strictly necessary but well-organized, making it easy to scan. A score of 4 reflects strong structure with minor room for tightening.

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

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

For a mutation tool with destructiveHint, the description covers the key operational details: NF-e only, field limitations, supersession, 20-letter cap, and verbatim transmission. It also distinguishes from cancellation/reissue. It does not describe the output schema (which is provided separately) or mention authentication or error conditions, but those are less critical given the existing output schema and the thoroughness of the description.

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 0%, so the description must compensate for parameter meaning. It does not explicitly explain 'access_key' or the 'correction' field beyond the general context. The term 'correction' is implicitly the letter text, but there is no mention of format, length constraints (minLength 15), or what access_key represents (e.g., the NF-e access key). This is a notable gap given zero schema documentation.

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

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

The description opens with a precise action: 'File an electronic correction letter (CC-e) against an NF-e.' It immediately distinguishes from NFS-e and explicitly states it corrects wording and non-fiscal fields only, setting it apart from cancel_invoice and reissue_invoice siblings. The verb and resource are specific, and the scope is unambiguous.

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

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

The description gives explicit when-to-use guidance (for wording and non-fiscal field corrections) and when-not-to-use guidance (cannot change values, taxes, recipient, or products; those require cancelling and reissuing). It also clarifies NF-e only, not NFS-e, and warns that using it for amounts is wrong and only discovered at audit. This is thorough routing to alternatives.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds three distinct behaviors: the PDF arrives base64-encoded in content_base64, the XML is the legally authoritative document (not this PDF), and a 502 error signals authorizer unavailability rather than invoice invalidity. This is rich error and return-format context that annotations cannot convey. No contradiction with annotations.

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

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

The purpose is front-loaded in the first sentence, followed by scope, return format, legal context, and error interpretation. Five sentences each carry distinct information with no filler or repetition. Slightly long for a 2-parameter tool, but every sentence earns its place given the valuable behavioral context it conveys.

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 2-param read tool with an output schema present, the description is nearly complete: it covers output encoding (base64 in content_base64), legal significance, and error interpretation. The only meaningful gap is the undocumented access_key parameter, but the output schema and annotations cover most of the remaining surface area.

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 0% schema description coverage, the description must compensate for both parameters. It handles document_type well by mapping the enum values (nfe→DANFE, nfse→DANFSe), which adds meaning beyond the raw enum list. However, access_key is never described - its purpose, format, or constraints are left entirely to the schema, which provides only a title. Compensation is partial.

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

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

The opening line 'Return the printable rendering of a document, as a PDF' states a specific resource and output format. The follow-up clarifies scope ('Works for both types — a DANFE for nfe, a DANFSe for nfse'), which helps differentiate it from sibling tools like consult_invoice (which presumably returns XML). The verb 'Return' is generic, but the resource and format make the purpose clear.

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

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

Usage is implied rather than stated. The description hints that the XML (not the PDF) is the legally valid document, which subtly suggests an agent might prefer another tool for legal/validation purposes, but it never names an alternative like consult_invoice or states explicit when-to/when-not-to conditions. The scope note about both types is helpful but not a routing guide.

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

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

Annotations already mark readOnly, idempotent, non-destructive; the description adds the critical nuance that rows are attempts (not documents), ordered oldest first, and only the last describes current state. It also instructs to quote the authority's message, which is behavioral guidance beyond the annotations. No contradiction.

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

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

Structured into clear paragraphs: purpose, usage, row semantics. Every sentence adds value, front-loads the main purpose, and provides actionable guidance. No filler or repetition.

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

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

Despite having an output schema, the description conveys the conceptual return shape (attempts with authority code, message, raw request/response). It covers how to find the id, ordering, and how to interpret results. Nothing an agent needs to invoke 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 0% and the schema only says 'invoice_id' is a string. The description explains why invoice_id is needed (rejected docs lack access key), how to obtain it (from list_invoices), and its relationship to reissue_invoice. This fully compensates for the schema gap.

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

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

The description opens with a specific verb and resource: 'Show every attempt made for one invoice and what came back.' It immediately differentiates from consult_invoice by clarifying it answers 'why was it rejected' with the authority's code, message, and raw request/response. This is unambiguous and distinguishes it from siblings.

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

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

Explicitly names the scenario ('why was it rejected'), contrasts with consult_invoice, and explains that a rejected document has no access key, so invoice_id must come from list_invoices. It even parallels reissue_invoice for lookup semantics. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description goes beyond the destructiveHint annotation by explicitly stating the operation is irreversible and that declared numbers can never be used again. It also warns about the risk of burning numbers if the range is wrong, and mentions SDK-level validations before transmission, giving a full picture of the tool's side effects.

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

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

The description is somewhat lengthy but every sentence adds critical information about usage, constraints, and side effects. The structure is clear, with repeated emphasis on key points (irreversibility, application scope, and confirmation) that are essential for safe invocation.

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

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

Given the operation's destructive and irreversible nature, the description covers all necessary context: when to use it, when not to use it, what validation the SDK performs, and the need for user confirmation. The existence of an output schema is not relevant to explaining the tool's behavior, and no critical context appears 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?

While the schema lists parameters without descriptions, the tool description provides meaningful context: it explains the reason must be 15-255 characters and that the range must be non-backwards. It does not define 'series' explicitly, but the overall purpose and constraints give sufficient guidance for an agent to infer the parameters' roles.

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

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

The description clearly states the tool's purpose: declaring an NF-e numbering range as reserved but unused, to maintain continuous numbering. It explicitly contrasts this with issuing a new document and with canceling an authorized document, making it distinct from sibling tools like 'cancel_invoice' and 'issue_invoice'.

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

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

The description provides explicit usage guidance, including that it applies only to never-authorized numbers, that authorized documents should be canceled instead, and that the user must confirm the range before calling. It also indicates the SDK will refuse backwards ranges and invalid reason lengths, which helps the agent avoid invalid calls.

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

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

The description goes beyond annotations by explaining side effects: it 'produces a legal fiscal document' and details the consequences of missing an idempotency key—another document, burned number, and cancellation deadline. This is far more transparent than the annotations alone.

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

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

The description is long but densely packed with essential information, structured into logical segments (document types, validation, idempotency). Every sentence adds operational value, with no fluff or redundancy, making it efficient despite its length.

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

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

Given the complexity of Brazilian fiscal documents, the description covers all critical aspects: document type differences, validation workflow, idempotency semantics, field requirements, and even cancellation deadlines. Combined with the output schema, an agent has sufficient context to invoke the tool correctly.

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

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

Many parameters are explained in detail, such as unit_price vs amount, service_code fallback, and recipient_address requirements for NFE. Since the schema itself has minimal descriptions (0% coverage), this description fully compensates by clarifying the meaning and relationships of key fields.

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

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

The description clearly states the tool's action: 'Issue a Brazilian fiscal document: NFS-e or NFE' and emphasizes it produces a legal document. It distinguishes between NFS-e (services) and NFE (goods), making the purpose unambiguous even without comparing to siblings.

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

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

Extensive guidance is provided: when to confirm inferred data, when to call validate_invoice_payload, how to handle idempotency_key for retries, and specific field requirements for each document type. It also warns against partial NFE submissions, leaving little ambiguity about the correct invocation.

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

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

Annotations already mark the tool as read-only and idempotent, and the description aligns with these without contradiction. It adds valuable behavioral details beyond annotations: the status synonym handling ('authorized' = 'issued'), the guarantee that every row carries the needed identifiers, and the specific caveat that rejected rows lack an access key. This is substantive and non-redundant.

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 longer than typical but every sentence earns its place. It opens with the core purpose, then layers constraints, usage hints, synonym nuances, and row semantics in a logical order. There is no fluff or repetition; the density of useful information justifies the length.

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

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

Given that an output schema exists (so return format is already documented), the description covers all other essential context: ordering, one-document-type-at-a-time behavior, synonym handling, identifier semantics, and rejected-row behavior. No critical detail an agent needs to call this tool 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 0%, so the description must compensate, and it does thoroughly. It explains document_type ('nfse' for services, 'nfe' for goods), interprets status (synonym, rejected implications), and clarifies the meaning of the row output (id vs access_key). Even though limit and offset are not explicitly described, their schema defaults and bounds make them self-evident; the description adds value where it is needed most.

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 precise verb-resource pair ('List the invoices this company issued') and adds ordering (newest first), which clearly identifies the tool's function. It also differentiates from siblings by specifying that it only returns issued (not received) invoices and references other tools that consume the returned identifiers, making it unambiguous which tool to select.

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

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

The description gives explicit usage scenarios ('my last invoices', 'what was rejected today', finding a document without an access key) and states a key constraint (one document type at a time). It also clarifies the read-only nature and the importance of passing the correct document_type, effectively directing the agent when to use this tool over alternatives.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that it reads what the API already collected and never calls the tax authority, which is useful side-effect transparency. The daily-cap phrase is slightly ambiguous but does not contradict the annotations.

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

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

The first sentence is strong and concise, but the later prose about 'manifestation' and 'summary only' is repetitive and confusing. Some sentences could be tightened or removed without losing core meaning.

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?

An output schema exists, so return-value details do not need to be in the description. However, the missing parameter explanation leaves a meaningful operational gap, and the ambiguous remarks about daily caps reduce completeness.

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

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

The schema has two parameters with no descriptions and 0% schema description coverage. The description does not mention limit or offset at all, so the agent gets no guidance on pagination, defaults, or maximum values.

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

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

States a specific verb ('List') and a clear object: NF-e documents issued by other companies against this one. It also explicitly contrasts with list_invoices, making the distinction obvious.

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?

Directly names list_invoices as the alternative and explains the difference: that one shows issued documents, this one shows received documents. It also states the tool is read-only and never calls the tax authority, which helps the agent decide when to use it.

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

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

The description goes well beyond the annotations, which only indicate destructiveHint and non-idempotence. It explicitly states the action is 'legally binding and irreversible once the tax authority accepts it,' warns that two positions (210220 and 210240) are accusations against the issuer, and details that only 210240 accepts a reason and requires one. This adds critical behavioral context that the annotations do not convey.

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

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

The description is relatively long but every sentence contributes necessary information. It front-loads the purpose and then adds warnings and parameter details in a logical order. It could be slightly more condensed without losing essential guidance, but it remains efficient given the complexity of the 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?

Given the tool's legal and irreversible nature, the description is remarkably complete. It covers the purpose, the four positions, the reason requirement, confirmation steps, and caution against misusing accusatory codes. The presence of an output schema covers the response format, so nothing critical is missing for correct invocation.

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

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

With schema description coverage at 0%, the description carries the full burden. It explains the meaning of each manifestation enum value (what each code confirms or denies) and specifies the reason parameter's behavior—that it is required only for 210240 and causes refusal for others if sent. This adds substantial semantic value beyond the bare schema titles and enum.

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

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

The description opens with a clear, specific verb and resource: 'Declare this company's position on a document issued against it.' It then enumerates the four possible positions (210200, 210210, 210220, 210240) with their meanings, making the tool's function unambiguous and easily distinguished from siblings like issue_invoice or cancel_invoice.

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

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

The description clearly states when to use the tool (when the company needs to declare a position on a received document) and provides important usage constraints, such as requiring human confirmation due to legal binding and instructing to ask when unsure rather than selecting accusatory positions. However, it does not explicitly compare against alternative tools or mention when not to use it in favor of another, so it stops short of a 5.

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

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

Annotations already mark it destructive/non-read-only, and the description adds concrete side effects: reissue 'consumes a credit like a new issuance' and uses an idempotency_key for the same reason as issue_invoice. It also clarifies that a rejected document has no access key, which helps set expectations about the identifier. It does not spell out every destructive consequence, but the annotations cover the core flag.

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

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

Three sentences, front-loaded with the core operation, then compact clarifications. The phrasing ('A rejected document never got one') is slightly indirect, but each sentence earns its place and there is no redundant schema repetition.

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

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

Despite 11 siblings and fairly minimal schema descriptions, the description gives enough context to select this tool and invoke it correctly: it names the target state (rejected after fix), the identifier distinction, and the idempotency key rationale. With an output schema present, the lack of return-value prose is acceptable.

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 zero schema descriptions, the description compensates: invoice_id is explained as 'the local invoice_id, not the access key,' and idempotency_key is motivated by the credit consumption parallel to a new issuance. Both parameters receive meaningful semantic context beyond their TypeScript types.

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

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

The description opens with a specific conditional action: 'Retry a rejected invoice after the data that caused the rejection was fixed.' It further distinguishes reissue from related operations by stating an authorized invoice is 'corrected or cancelled, never reissued,' making the tool's object and scope clear.

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

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

It explicitly defines the trigger: only after a rejection fix, use reissue. It also provides boundary guidance: authorized invoices should be corrected/cancelled, not reissued, and explains that like a new issuance it consumes a credit, which signals when to reach for this tool rather than a correction or document retrieval sibling.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description reinforces this with 'Nothing is sent to the tax authority and no document is created' and adds behavioral context by detailing what is checked (field formats, nfe-specific ncm/cfop and address) and what is not (cross-field/fiscal rules). This exceeds annotation coverage without contradiction.

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

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

The description is three short paragraphs with the core purpose front-loaded. Each sentence adds value: the summary, the safety reassurance, the specific checks, and the limitation. It is slightly verbose but not padded, and the structure is logical.

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 validation tool with an output schema, the description covers usage context, limitations, and key validation specifics. It doesn't fully enumerate all param requirements or the exact validation rules, but it provides enough for an agent to decide when and why to call it. The presence of an output schema reduces the need to explain return values.

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 has 0% description coverage, so the description must compensate. It references items and recipient_address in the nfe context, implying their significance, and document_type is covered by the enum. However, it doesn't explicitly detail each parameter's format or constraints, leaving some interpretation to the agent. Still, it adds meaningful context beyond the bare 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 clearly states the tool validates invoice data against field rules without issuing anything. It distinguishes itself from issue_invoice and specifically mentions the nfe checks (ncm, cfop, recipient address), making its purpose unambiguous.

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

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

It explicitly advises calling this before issue_invoice when a field was inferred, and warns that it does not replace issuing since authorizer rules are only checked on transmission. This gives clear when-to-use and when-not-to-use guidance, differentiating it from sibling tools.

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