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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context: output is an XML string (not a submission), it is KSeF-compliant, and the seller's tax_id must be a Polish NIP (10 digits). However, it does not describe potential validation behavior, error conditions, or whether the tool performs any side-effect-free transformation beyond what is implied.

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 concise sentences with no fluff: purpose, output, and the key country-specific constraint. It is front-loaded with the main action and output type, and every sentence earns its place.

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

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

Given the highly detailed 100%-coverage schema and the existence of an output schema, the description covers the essentials: what it generates, the return type, and the Polish NIP requirement. It is adequate for an agent to call the tool correctly, though it could be improved by explicitly stating that it only generates and does not submit or validate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one meaningful constraint not in the schema—'The seller's tax_id must be a Polish NIP (10 digits)'—which helps an agent populate the nested seller.tax_id correctly. Beyond that, the description defers to the already-rich inline schema descriptions.

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 a specific verb and resource: 'Generate a KSeF-compliant FA(2) XML invoice from structured invoice data.' It also specifies the output format ('FA(2) XML string ready for submission to KSeF'), which distinguishes it from submission, validation, and parsing siblings. However, it does not explicitly name generate_fa3_invoice or generate_peppol_invoice as alternatives, so differentiation relies mostly on the tool name and format.

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

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

The description implies usage context: call this when you have structured invoice data and need an FA(2) XML string for KSeF, and the 'ready for submission' phrase implies the tool does not submit. It does not explicitly state when to prefer generate_fa3_invoice, validate_fa2_invoice, or submit_invoice_to_ksef, and no alternatives are named.

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?

No annotations are provided, so the description carries the disclosure burden. It discloses the return value (FA(3) XML string ready for submit_invoice_to_ksef), the F(A)3 compliance requirement, and tax-identifier constraints including the <BrakID> edge case. It does not describe error/validation behavior, but for a pure generation tool this is reasonably transparent.

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

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

The description is compact and front-loaded with the core action and output format, followed by workflow ordering and key constraints. Every sentence earns its place, with no filler or redundant restatement of schema details.

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 a very rich nested schema and an output schema, so the description need not restate field details. It provides the critical workflow context (use before submit_invoice_to_ksef, not generate_fa2_invoice) and important country-specific constraints. The unresolved contradiction about representing an absent buyer tax ID is the main completeness gap.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add useful context such as seller NIP format and buyer tax-id alternatives. However, the instruction to leave tax_id.identifier empty for absent buyer tax IDs contradicts the schema, which requires tax_id and enforces minLength: 1 on identifier. The 'set alt_tax_id' guidance for EU VAT numbers also reads inconsistently with alt_tax_id's schema meaning, so the added value is undercut by misleading edge-case guidance.

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

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

States a specific verb and resource: generates a KSeF-compliant FA(3) XML invoice from structured invoice data. It also distinguishes itself from the sibling generate_fa2_invoice, so an agent can identify the correct tool without inspecting schemas.

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 use this tool rather than generate_fa2_invoice and to call it before submit_invoice_to_ksef. It also explains that FA(3) is required for all new KSeF API v2 submissions, giving clear when/when-not 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?

No annotations are provided, so the description carries the full behavioral burden. It says the tool generates an XML invoice, but does not disclose whether it validates input, returns XML directly, persists anything, or transmits to the Peppol network. The generate-versus-submit behavior is left ambiguous.

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 first sentence defines the output format, and the second provides usage routing. Every sentence earns its place.

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

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

The tool is complex with deeply nested inputs, but the schema is richly documented and an output schema exists, so return-value details are not needed. The description provides the essential selection and routing context; the main remaining gap is the unstated generate-versus-submit behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-level guidance, but the detailed invoice object schema already documents the fields, formats, and country-specific meanings, so the agent can still construct the parameter correctly.

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

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

The description states a specific verb and resource: 'Generate a Peppol BIS Billing 3.0 / EN 16931 UBL 2.1 XML invoice.' It also distinguishes the tool from siblings by explicitly framing it as cross-border B2B via Peppol, which separates it from the Polish FA invoice tools.

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

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

The description explicitly says when to use this tool ('Use this for cross-border B2B invoicing via the Peppol network') and names a concrete alternative with its own condition ('For domestic Polish invoicing, use generate_fa2_invoice instead'). This is clear routing 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?

No annotations are provided, so the description carries the behavioral disclosure burden. 'Retrieve' and 'processing status' strongly imply a read-only operation, but the description does not mention potential error cases, polling semantics, or confirmation that no state changes occur. The read-only implication compensates partly for the missing 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 a single, front-loaded sentence with no filler or redundant wording. It states the operation, the target resource, and the relevant API version efficiently.

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 tool with one required parameter and an output schema, the description is mostly sufficient for an agent to invoke it correctly. The only notable gap is the lack of explicit guidance about when to use this versus the search-related sibling or how to handle unresolved statuses, but the output schema likely covers response details.

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 description coverage is 100%, and the parameter schema already explains the '{sessionRef}:{invoiceRef}' format and the option to pass only the sessionRef for session status. The tool description adds no additional parameter-level meaning beyond that, so the baseline score of 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 clearly identifies the operation as retrieving the processing status of a KSeF invoice, with an explicit version qualifier ('API v2'). It is specific about verb and resource, though it does not explicitly distinguish itself from siblings like search_ksef_invoices.

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 word 'submitted' implies the tool should be used after invoice submission, and the sibling submit_invoice_to_ksef provides contextual contrast. However, there is no explicit statement about when to use this tool instead of alternatives like search_ksef_invoices or when it is not appropriate.

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

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

With no annotations, the description carries the full burden, and it does disclose the primary behavior: converting XML into a nested dictionary with named keys. However, it does not mention error behavior on malformed XML, format assumptions, or whether parsing is strict or lenient, leaving notable gaps for a parsing tool.

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

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

The description is two tight sentences with no filler. The main action and resource are front-loaded, and the second sentence economically summarizes the return structure.

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

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

For a single-parameter parser with an output schema, the description covers the essential call pattern: pass FA(2) XML content and receive a dict with named sections. It is less complete about error conditions, supported KSeF versions, and edge cases such as empty or invalid XML, which an agent would need for robust handling.

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 only defines xml_content as a string with no description, while the tool description adds that it should contain a KSeF FA(2) XML invoice. This provides useful meaning beyond the raw schema, but it does not cover encoding details, XML structure expectations, or how malformed content is handled.

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

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

The description uses a specific verb ('Parse') and a precise resource ('a KSeF FA(2) XML invoice'), and it states the output is a structured dictionary with clear top-level keys. This clearly separates it from siblings like generate_fa2_invoice and validate_fa2_invoice, which perform different operations on the same document type.

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

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

The intended use is implied by the verb 'Parse' and the reference to FA(2) XML invoices, but there is no explicit guidance about when to choose this tool over validate_fa2_invoice or generate_fa2_invoice. No exclusions, prerequisites, or alternative-use conditions are stated.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It states a read-style query operation but does not mention pagination, result limits, KSeF environment specifics, or whether the query has any filtering side effects. The phrase 'Query invoices stored in KSeF' is clear but minimal.

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 a single efficient sentence with no filler. It front-loads the action and resource, making it easy to scan, though it does sacrifice some useful detail for brevity.

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

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

With three parameters, no annotations, and no schema descriptions, the description leaves critical input semantics unexplained. The output schema exists but does not help an agent provide correct inputs, especially for subject_type and date formatting. The tool description is not sufficient for a confident first call.

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

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

Schema descriptions are entirely empty (0% coverage), so the description must compensate. It clarifies that date_from and date_to define the date range, but it does not explain their expected format or the meaning of subject_type, which remains completely undocumented.

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

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

The description uses a specific verb ('Query') with a clear resource ('invoices stored in KSeF') and a defined scope ('for a date range'). This clearly separates it from siblings like submit_invoice_to_ksef, generate_fa2_invoice, and validate_polish_nip.

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

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

No guidance is provided about when to use this tool versus alternatives such as get_ksef_invoice_status. The agent is left to infer the intended use from the tool name and description rather than being told which sibling handles status checks or individual invoice retrieval.

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?

No annotations are provided, so the description must carry the behavioral burden. It discloses the FA(3) format requirement but does not mention side effects of submission, authentication prerequisites, reversibility, or potential status/error behavior. For a mutation tool, this leaves important operational behavior undisclosed.

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 core purpose is front-loaded in the first sentence, and the following sentences give relevant format guidance. The roadmap note is slightly extraneous and could confuse, but overall the description is compact and structured well.

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 documentation is not the description's burden. However, with no annotations, the description should cover prerequisites such as session_token acquisition and submission side effects; it only covers the format constraint. This is sufficient for the basic input but incomplete for confident 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 coverage is only 50%; xml_content has no schema description, while session_token has an auth flow link. The description adds meaning to xml_content by requiring FA(3) XML, but it does not specify encoding, structure, or how the content must be embedded, so it only partially 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?

States a specific verb, resource, and version: 'Submit a FA(3) XML invoice to the KSeF platform (API v2).' It also distinguishes itself from generate_fa2_invoice by clarifying the target format, so an agent can tell this is the submission tool, not a generator or validator.

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 warns that generate_fa2_invoice produces FA(2) XML that KSeF v2 does not accept and should only be used for validation or parsing. However, it does not point to generate_fa3_invoice as the correct companion generator, and the roadmap note muddies whether FA(3) generation is actually available.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the conditional XSD validation ('when the official schema is present') and explains the return type as a DocumentValidationResult with errors and warnings, giving useful behavioral context beyond the tool name.

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

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

The description is two sentences with no filler. It front-loads the core action and then adds the key behavioral details about validation steps and output, every sentence earning its place.

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

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

For a single-parameter validation tool with an output schema, the description is largely sufficient. It covers the validation logic, the conditional schema dependency, and the result type, though it could add a sentence about when validation is appropriate relative to submission.

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. It identifies the input as a KSeF FA(2) XML invoice, which makes the xml_content parameter largely inferable, but it does not explicitly define the parameter as the raw XML string or specify any constraints such as encoding or size.

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 a KSeF FA(2) XML invoice, naming both the specific resource and the action. It further distinguishes the scope by mentioning XSD validation and Polish business-rule checks, which separates it from sibling validation and generation tools.

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

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

The description explains what the tool does but offers no guidance on when to use it versus alternatives such as parse_fa2_invoice, generate_fa2_invoice, or submit_invoice_to_ksef. There is no mention of pre-submission validation, exclusion conditions, or recommended workflow context.

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?

There are no annotations, so the description carries the burden. It discloses the algorithm, accepted formatting, and return shape, which is solid for a simple validation tool, though it does not cover malformed-input edge cases.

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

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

Three short, front-loaded sentences with no filler. Each sentence adds distinct value: purpose, algorithm/format, and return contract.

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

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

For a single-parameter validator, the description covers what the tool does, how it validates, what formats are accepted, and what it returns. With an output schema already present, no critical information 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?

The schema only says 'string', so the description adds important meaning: the NIP should be 10 digits and may include dashes or spaces. It stops short of giving examples or exact normalization rules.

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

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

The description uses a specific verb ('Validate'), names the exact resource ('Polish NIP'), and states the checksum algorithm, so an agent can distinguish it from validate_polish_regon and the invoice tools without opening the schema.

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

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

It states what input is accepted and implies when to use it, but it never describes when to prefer this over validate_polish_regon or when not to use it. The usage context is clear but not made explicit.

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

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

With no annotations provided, the description carries the full burden. It discloses the return shape ('valid', 'regon', 'length'), signals a safe read-only validation operation, and specifies the accepted 9 or 14 digit format. It does not mention checksum behavior or error handling for malformed input, but for a simple validator this is a minor gap.

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

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

Two short sentences with no filler. The action and target are front-loaded, and the return format is stated compactly. Every phrase earns its place.

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

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

For a simple single-parameter validation tool with an output schema, the description is nearly complete. It covers what is validated, the accepted length, and the return keys. Missing details like checksum validation or behavior on invalid formats are useful but not critical for invoking 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?

Schema coverage is 0%, so the description must compensate for the bare string parameter. It does so by explaining REGON is a 9 or 14 digit business registry number, which gives the agent concrete format expectations beyond the schema. It does not discuss normalization or edge cases, but the single parameter is adequately clarified.

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

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

The description names a specific verb ('Validate') and resource ('Polish REGON — 9 or 14 digits'), clearly distinguishing it from siblings like validate_polish_nip. The parenthetical format detail makes the tool's exact purpose immediately recognizable.

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 clearly implies when to use this tool: whenever a Polish REGON number needs validation. It does not explicitly name alternatives or exclusions, but the resource-specific wording provides sufficient context for an agent to select it over NIP or invoice validation tools.

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