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?

Despite the annotations (destructiveHint, non-idempotent), the description goes well beyond them: it discloses the legal nature of the document, the SEFAZ rejection of incomplete NF-e, the refusal when unit_price and amount conflict, and the full replay-vs-issue-again behavior of idempotency_key, including the need to cancel to undo. This is exactly the kind of behavioral context an agent needs and the schema cannot express.

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 each sentence earns its place: the purpose is front-loaded, then pricing semantics, then the two document type branches, then idempotency guidance. There's minimal fluff, and the paragraphs are grouped by responsibility, making it easy to scan. For a tool this complex, this level of detail is not almost at all.

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 complex nested schema and the existence of an output schema, the description covers the decision points an agent needs to invoke this tool correctly: which validation is required, what each document type demands, and what idempotency hazards exist. It also flags the user-confirmation step, which is a critical interaction requirement. No obvious gaps remain for safe 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?

Schema description coverage is 0%, so the description carries the full semantic load and does so thoroughly. It explains document_type's nfse vs nfe field requirements, the difference between unit_price and amount, when recipient_address becomes mandatory, and the business meaning of idempotency_key. Even though it does not narrate the obviously named tax_id, client_name, number, and series, it covers every ambiguity an agent is likely to face 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?

The first sentence states a specific verb and resource: 'Issue a Brazilian fiscal document: NFS-e or NF-e.' This clearly identifies the tool as the issuance action, distinct from siblings like reissue_invoice, cancel_invoice, and validate_invoice_payload. The two document_type variants are also exposed, so an agent immediately knows what the tool does.

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: confirm the user's data before calling when any field was inferred, call validate_invoice_payload first for partially inferred NF-e data, and pass idempotency_key whenever a retry might occur. It even describes the when-not-to case by warning that without a key, retries issue a duplicate document. This passes the bar of naming the alternative tool and the condition that selects 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine value by disclosing the temporal dynamics: the answer grows with source data, and an absent name is absent today, not forever. This enriches the open-world semantics without contradicting 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?

Extremely compact — three short sentences carrying the purpose, the usage trigger, and the behavioral caveat. Nothing is wasted, and the key question is front-loaded.

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

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

With an output schema present, full parameter coverage, and annotations carrying the safety profile, the description is nearly complete for a simple listing tool. The only minor omission is explicit naming of what a 'fiscal kind' is, though sibling context makes it reasonably inferable.

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 fully documents the 'country' parameter. The description adds no parameter-specific detail beyond what the schema already states, matching the baseline 3 for fully covered schemas.

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

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

States a specific verb+resource ('list' classifications with 'data') scoped by country. The purpose is immediately clear and distinct from all siblings, which concern invoice operations, fiscal codes, and taxpayer lookups — none list fiscal classifications.

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?

'Ask this before assuming a classification exists' gives clear, actionable usage timing. However, it names no explicit alternatives and offers no when-not-to-use condition, so the guidance is context-rich but lacks exclusionary detail.

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 adds meaningful behavioral context beyond the annotations: 404 means invalid code, not a lookup failure, and metadata varies by kind with concrete examples. This disclosure helps the agent interpret responses correctly and avoid useless retries.

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 tightly organized: purpose first, then when to use, then failure semantics, then metadata variation. Every sentence adds distinct value with no redundancy or 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 simple lookup tool with an output schema, the description covers the key operational details: use case, failure mode, retry guidance, and kind-dependent metadata. Nothing needed for correct invocation 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?

The input schema already covers all parameters clearly with 100% schema description coverage, including examples and validation constraints. The description adds useful context about metadata behavior, but does not need to repeat parameter details; 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 states a precise operation: resolve one code of one classification when both are known. It clearly distinguishes this from broader searching by emphasizing the single-code, confirmatory 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?

The description gives a clear use case: confirm a code before putting it on a document to avoid rejected issuance. It also explains that a 404 means the code is wrong and should not be retried, though it does not explicitly name sibling alternatives like search_fiscal_codes.

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=false, idempotentHint=true, and destructiveHint=falseikuha. The description adds essential behavioral context beyond these: the registry reloads monthly, so a 404 does not imply nonexistence. This is critical behavioral information that annotations do not convey, and it could easily lead to misinterpretation of lookup failures. The description does not contradict 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 description is appropriately sized, with no fluff. Key points are front-loaded: the primary purpose and usage scenario come firstainer, followed by the explicit exclusions and critical 404 handling. Each sentence earns its place, contributing crucial operational guidance. Perfectly structured for quick agent comprehension.

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 simplicity (2 params, one required), an output schema exists to explain returns, and annotations cover safety/idempotency. The description covers all necessary usage details: exact match, no partial search, the 404 caveat, and how to handle it. Nothing gaping missing for an agent to call correctly.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds important context for both parameters: the tax_id must be exact and allows punctuation, and clarifies the 14-digit format for CNPJ (though schema says that). For country, the description notes that 'a code means nothing without it' (reinforcing the need for context) and explains the default is Brazil as a deliberate choice, not a guess. This adds value 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 clearly states the tool's specific purpose: 'Look up one taxpayer by exact tax id, to confirm who it is.' It distinguishes this from name/prefix search, explicitly noting there is no search by those means presumably available in sibling tools. The verb+resource is specific, and it names the exact scenario (check recipient's name before issuing).

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 guidance: use it to confirm identity before issuing against a recipient. It explicitly states when not to use it: no search by name, prefix, or state. It also handles the 404 edge case, instructing the agent to explain to the user rather than report invalid, and never to turn a 404 into a validation rule. This is thorough usage 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 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?

Beyond the readOnly/idempotent annotations, the description reveals useful behavioral traits: unset `kind` searches all classifications and is the most expensive call, rows are ordered by kind then code, and there is no sort argument. This prevents the agent from inventing a sort parameter and sets clear performance expectations.

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 tightly written and front-loaded with the core purpose in the first sentence. Every subsequent sentence earns its place: cost guidance, when to set `kind`, and the no-sort behavior. It is appropriately sized for a tool with five parameters.

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 rich annotations, fully described schema, and output schema, the description covers the remaining practical concerns: use case, cost, paging, ordering, and absence of sorting. Nothing the agent needs to invoke the 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 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema, especially for `kind` (unset means all classifications and is expensive; set it when the question names one). It also disambiguates the pagination intent with the "no sort" note. This lifts it above 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?

The description clearly states the resource (fiscal codes) and the two main actions: searching by description and paging through the table. The example "what NCM is a keyboard" makes the purpose concrete, but it does not explicitly contrast with sibling tools like lookup_fiscal_code or list_fiscal_kinds, which keeps it just 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?

The description gives excellent usage context: prefer this lookup over guessing from memory, and set `kind` whenever the question already names one to avoid the most expensive call. It lacks explicit when-not-to-use statements naming sibling alternatives, so it stops short of fully explicit routing.

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.