GCC e-Invoice Preflight Oracle

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description's job is to add context, and it does: it discloses cost ('Free') and, importantly, that documents are validated in memory and never stored or logged. It also sketches the verdict vocabulary (ACCEPTED | ACCEPTED_WITH_WARNINGS | REJECTED) and finding severities, which helps an agent interpret results; rate limits and error behavior are the only notable omissions.

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

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

Front-loaded with the core action and derivation rule, then example, then response shape. It loses a little efficiency by enumerating the full response field list (findings[], counts, data_confidence, sources[], disclaimer) that the output schema already provides, but every clause remains readable and relevant.

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, annotations, and a single fully-described parameter, the definition covers what the tool does, its cost, and its privacy posture. It never says explicitly where the derived Peppol endpoint appears in the response, nor how it relates to validate_invoice, which is the one real gap for an agent deciding between the two.

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

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

Schema coverage is 100% and the single parameter is documented, so the baseline is 3; the description goes beyond by stating the 15-digit length rule and supplying a formatted sample ('100 1234 5670 0003') that demonstrates the accepted spacing, which the schema only alludes to.

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 ('Format check of a UAE Tax Registration Number') plus a secondary function (deriving the TIN / Peppol participant identifier with scheme 0235). The 'format check' framing implicitly separates it from sibling validate_invoice, which handles whole documents, so an agent can pick between them from the text alone.

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

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

Gives useful calling context ('Free', a concrete example TRN) and the format-only scope, but never states when to prefer this over validate_invoice or the readiness_report path, nor any exclusion such as 'does not verify the TRN against a registry'. Usage is implied rather than directed.

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/non-destructive/idempotent annotations, the description discloses that documents are validated in memory and never stored or logged, and it provides a detailed response shape with verdict, findings, counts, confidence, sources, and disclaimer. The only concern is the internal tension between 'without validating' and the described validation verdict/findings.

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 front-loads the extracted fields well, but it is a dense run-on list, and the response details are lengthy despite the presence of an output schema. The information is useful but not optimally structured for quick agent parsing.

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 output schema and annotations, the description is largely complete: it covers purpose, behavior, privacy/storage, cost, and response contents. The main gap is the unexplained required xml input parameter, which leaves the calling contract underspecified.

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 one required parameter named 'xml' with an empty description and 0% schema description coverage. The tool title implies a UBL invoice input, but the description never explains the xml parameter's expected format, encoding, size, or whether it is raw XML versus base64.

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: reading key fields of a UBL invoice, including seller/buyer data, dates, totals, VAT, payment means, and attachments. It also distinguishes the tool from validation by saying 'without validating', though the later mention of verdict/findings and in-memory validation creates some ambiguity.

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

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

The phrase 'without validating. Free.' implies this is the non-validating, no-cost extraction option, which helps distinguish it from validate_invoice. However, it does not explicitly say when to use this tool versus check_trn, readiness_report, or validate_invoice, nor does it state any exclusions.

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 the safety profile is covered. The description adds cost ('Free') and a non-storage guarantee, but that guarantee is attached to 'Documents are validated in memory', which describes validation behavior rather than a rule-listing read — an irrelevant and potentially misleading behavioral claim.

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 front-loaded well with purpose and filters, but roughly half its length is a response-format dump (verdict, findings[], counts, data_confidence, sources[], disclaimer) that does not belong to a rule-listing tool and duplicates the existing output schema. That block crowds out more useful content such as jurisdiction semantics.

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 the long return-value enumeration is redundant, while the genuinely unclear parts — what 'ae' vs 'ae-sb' jurisdiction selects and when to prefer this over validate_invoice — are never addressed. The copy-pasted validation response block makes the definition actively confusing for a read-only lookup tool.

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

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

Schema coverage is 33%: only 'contains' is documented in the schema. The description covers text filtering and severity filtering, and the severity enum (fatal | warning) is self-explanatory. However 'jurisdiction' (ae vs ae-sb, default ae) is explained nowhere in either the schema or the description, leaving a meaningful 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 opening clause gives a specific verb and resource: rule ids, severities and texts from the installed PINT AE Schematron, with the filterable dimensions named. It is distinguishable from validate_invoice, but the trailing 'Response: result with verdict ... findings[] ...' block describes a validation output, which blurs what this tool actually returns.

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?

'Free' plus a worked filter example (contains 'TaxPointDate') imply exploratory lookup usage, but there is no explicit statement of when to call this instead of validate_invoice or readiness_report, and no exclusions. The agent must infer that this is the discovery/introspection counterpart to validation.

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

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

Annotations already cover the read-only/idempotent/no-destruction profile, and the description adds genuinely new behavior: per-document billing, "validated in memory and never stored or logged", and synthesized confidence/disclaimer fields. The long response enumeration partly duplicates the existing output schema, which slightly dilutes the value.

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?

Purpose, use case, cost, and data-handling are front-loaded, which is right. But the third sentence is a lengthy field-by-field response listing that repeats the output schema rather than adding interpretation, so a chunk of the text does not earn 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?

Return values and data-retention behavior are well covered (and the output schema exists anyway), but for a 4-parameter batch validation tool the total silence on preflight and jurisdiction leaves an agent guessing on two of four inputs, one of which is an opaque enum.

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% and the two undocumented parameters, preflight (boolean, default true) and jurisdiction (auto|ae|ae-sb|sa), are never mentioned in the description. The description covers the output side and the html format, but says nothing about what preflight=false disables or how the jurisdiction enum should be chosen.

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?

"Batch preflight" plus "per-document verdicts, readiness percentage" gives a specific verb (validate in batch) and resource (e-invoices) and implicitly distinguishes itself from the single-document sibling validate_invoice, though it never names it. An agent can tell what it does 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?

"For a go-live check or an ERP regression suite" supplies clear when-to-use context, and the batch framing plus "Charged per document" signals scale/cost tradeoffs. It stops short of naming validate_invoice as the single-document alternative or stating when not 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?

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds valuable context beyond them: documents are validated in memory and never stored or logged. It also discloses the validation stages and verdict model, making the tool's behavior well understood.

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 front-loaded with the core purpose and validation scope, and it remains structured throughout. It is somewhat verbose in enumerating response fields even though an output schema exists, but the redundancy is not severe enough to impede use.

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 invoice validation, the definition is complete: it names the standards and checks, explains the verdict and findings model, and covers privacy behavior. With rich annotations, full schema coverage, and an output schema, no critical invocation context is missing.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds an example using xml and jurisdiction 'auto', but it does not meaningfully explain preflight or include_info beyond what the schema provides, so the 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 specific verb and resource: a full preflight validation of one UBL Invoice or CreditNote, including named checks and output verdicts. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as check_trn or readiness_report, leaving some routing inference to the agent.

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 gives a clear usage context: validating one invoice/credit note XML with full ruleset coverage and advisory checks. However, it does not state when not to use it or name alternatives like check_trn for single-field checks or readiness_report for broader reporting.

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 and closed-world, so safety is covered structurally. The description adds two genuinely new behavioral facts: the call is 'Free' and 'Documents are validated in memory and never stored or logged,' which matters for an agent handling invoice data. It stops short of rate limits or input-format failure modes.

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 correctly in the first clause, but the second sentence is a long comma-spliced inventory of response fields (verdict, findings[], counts, ruleset version, timings, data_confidence, estimated_items[], sources[], data_version, warnings[], disclaimer) that reads far past the point of usefulness.

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?

A single-parameter read tool with full annotation coverage and an output schema is well served here; the memory-only processing guarantee is the key missing piece an agent would need and it is present. The only issue is that the lengthy field inventory is largely redundant against the existing output schema.

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?

Only one parameter, and the schema already documents it at 100% coverage ('Base64 TLV content of a ZATCA QR code'). The description restates the same thing without adding format details such as whether padding, whitespace, or raw TLV bytes are accepted, so it neither compensates nor detracts.

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 (Decode) applied to a specific resource (base64 TLV of a Saudi e-invoice QR) and enumerates the decoded fields (seller name, VAT, timestamp, totals, hash, signature). The decode/encode split from sibling zatca_qr_encode is unambiguous from the verb alone.

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

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

Usage is only implied through the tool name and the phrase 'with phase detection and format issues' — an agent can infer this is for inspecting a QR payload, but nothing says when to prefer this over validate_invoice or extract_summary, and there are no stated preconditions on the input string.

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, and the description adds meaningful context beyond them: the operation is free, encoding is done in memory, and nothing is stored or logged. That privacy/cost disclosure is the kind of thing annotations cannot express. It does not, however, explain what happens with malformed phase-2 inputs.

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 sentence is excellent and front-loaded, but the bulk of the text enumerates return fields (verdict, findings[], counts, data_confidence, sources[], data_version, timings) that an output schema already covers. Worse, the xsd/schematron/ruleset 'documents are validated' phrasing reads as copied from a validation tool and dilutes focus.

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, the description need not explain returns, and it covers purpose, cost, and data-handling well. It is slightly incomplete in not clarifying how the optional phase-2 parameters interact with the required phase-1 set, or what an encoding failure looks like.

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

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

Schema coverage is already 89%, so the baseline is 3, but the description adds real semantic structure by distinguishing the five mandatory phase-1 fields from the optional phase-2 hash/signature/key tags. It does not map names to the phase groupings explicitly, and seller_name has an empty schema description.

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 (encode TLV fields into a base64 TLV string) and even names the destination artifacts (QR image, UBL QR reference). The encode/decode split against sibling zatca_qr_decode is unambiguous without comparing 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?

The description implies its use case (producing the QR payload) and notes it is free, but never states when to pick this over zatca_qr_decode, validate_invoice, or the other siblings, nor any precondition such as needing phase-2 keys for the optional tags. Usage is inferable but not guided.

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