create_voucher_type

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

Beyond the minimal annotations, the description discloses detailed behavior: the dual create/rename mode, the effect of numberingMethod, the real-world issue of blank voucher numbers if not set, the relationship of useAsManufacturingJournal to Stock Journal, and the escape hatch of extraFields. This is far more transparent than typical tool descriptions.

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 long and wraps many caveats into a single flowing paragraph, which can be a bit dense. However, every sentence delivers important operational knowledge, and the main purpose is stated upfront. It is appropriately detailed for the complexity of the operation, though slightly more structured formatting would improve readability.

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 description thoroughly covers the operation's semantics, edge cases, and relationships to other tools (e.g., create_stock_journal). It does not mention the return value or error behavior, but for a create/rename tool with no output schema, the focus on input-side behavior is arguably sufficient. A brief note on what it returns would make it fully complete.

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?

Every parameter has a schema description, and the narrative adds critical nuance for many of them: numberingMethod values and consequences, oldName for renaming, parent needing to exist, extraFields as an unvalidated escape hatch, and useAsManufacturingJournal's actual impact. This exceeds what the raw schema provides.

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's primary action ('Create a new custom Voucher Type') and extends to renaming/reconfiguring existing ones, which is a distinct scope. It differentiates from sibling tools by focusing on the Voucher Type master object and references the need to check get_voucher_types for valid parents.

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 explicit usage guidance: it tells the agent to check existing voucher types via get_voucher_types, explains when to pass oldName to rename vs. create, and warns about numberingMethod pitfalls. It stops short of an explicit 'use this instead of X' comparison with sibling tools, but the context is clear.

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