export_vat_return

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

With no annotations, the description carries the full burden and does so well on the traits that matter: it writes files to a specific directory tree, it conditionally emits the SH statement only when EU services exist, and it explicitly does not submit anything. It is silent on overwrite behavior when prior quarter files already exist and on what happens if the necessary underlying data is missing, which are the remaining behavioral unknowns.

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 compact sentences front-loaded with the output artifacts, followed by the destination and the crucial 'does not file' caveat. The path template is dense but earns its space because it encodes the naming convention. Slightly more formatting would help separate the conditional SH case from the unconditional outputs.

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 explained, and the description covers what is generated, where it lands, the EU-services condition, and the manual upload follow-up. Overwrite semantics and error conditions for an incomplete quarter are the notable omissions for a file-writing export 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 description coverage is 100%, so year, quarter, preview, and filed_on are already documented in the schema. The path template in the description implicitly shows how year and quarter are consumed and hints at quarterly granularity, but adds no meaning about preview or filed_on beyond what the schema states. 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 names the concrete artifacts produced (DPHDP3, DPHKH1, and conditionally DPHSHV) rather than just repeating 'VAT return' from the tool name, so it actually widens the scope the name suggests. It also states the target system (EPO) and the destination path, letting an agent identify the tool 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 makes clear this is the preparatory step in the filing workflow and that submission is manual afterwards, which tells the agent this tool should not be followed by any automated submit call. It does not address how it relates to the sibling tax_overview, which is the closest candidate for confusion, so it stops short of full alternative routing.

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