Upload Voucher File

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

Beyond the annotations, the description discloses practical behaviors: fileName derivation from filePath, contentType auto-detection for common image extensions, and mutual exclusivity of filePath/contentBase64. However, it does not mention what happens on success, upload side effects, or required MCP server permissions, leaving the annotation's openWorldHint unaddressed.

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 sentences long, front-loaded with the primary purpose, and every sentence adds needed information. There is no redundant or filler content; it is compact and structured for quick reading.

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 moderate complexity of the input (5 parameters with combinations) and no output schema, the description covers parameter selection and mutual exclusion comprehensively. It does not describe the return value or error scenarios, but for file upload tool this is a acceptable gap given the input-focused nature 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?

Although the schema already covers all parameters (100% coverage), the description adds crucial inter-parameter semantics: the mutual exclusion of filePath and contentBase64, the condition requiring fileName, and the auto-detection behavior for contentType. This goes well beyond the baseline schema descriptions and is essential for correct invocation.

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 and resource: 'Upload a file attachment to a bookkeeping voucher.' This clearly identifies the tool's function and distinguishes it from the sibling lexware_upload_file, which is a generic upload tool. The title and description align perfectly.

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 clear, actionable guidance on when to use filePath versus contentBase64, including the 'not both' constraint and when fileName is required. It does not explicitly compare this tool to sibling alternatives like lexware_upload_file, but the voucher-specific context makes the intended use obvious.

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