validate_invoice_ae

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

With no annotations present, the description carries the full burden and does so richly: it discloses the returned metadata.scope value, that EN16931_BASE_ONLY_SCOPE_WARNING and a known-limitations warning are always included, that BR-CO-09 fires on every genuine AE invoice, and that the variant parameter is inert. This is exactly the non-obvious behavioral context an agent needs.

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 and scope are stated first, then caveats, then the return note and variant clarification. It is long but every sentence carries a distinct caveat (never-checked overlay, always-included warnings, expected BR-CO-09 firing), so little reads as 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?

An output schema exists, so return values need not be narrated, and the description fills the remaining gaps: scope of validation, guaranteed warnings, expected false positives, downstream acceptance limits, and variant behavior. Nothing material to 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining that 'variant' is accepted only for interface stability and does not change which rules run. That is a substantive semantic clarification the schema default does not convey.

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 with scope: validating a PINT AE UBL 2.1 invoice against the CEN EN16931 base Schematron. It distinguishes itself from siblings like validate_tdd_ae and generate_invoice_ae by naming exactly which rule set runs and which overlay is excluded.

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 frames when the result is authoritative (base rules) and when it is not (PINT-AE jurisdiction overlay, real Access Point acceptance), which steers usage decisions. However, it never explicitly names an alternative tool or the condition that would route the agent elsewhere, leaving that to inference.

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