delivery_notes_storno

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

No annotations are provided, so the description carries the full burden. It discloses that the storno is created as a draft and can be issued separately — useful behavioral context. However, it doesn't mention that negated quantities are used (though this is implied in the first sentence), doesn't state whether the original delivery note is affected/destroyed/cancelled, and doesn't describe what happens if the source delivery note is not in an issuable state. For a mutation tool with no annotations, this is a moderate disclosure level.

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 two sentences, front-loaded with the core purpose, and includes the key behavioral note about draft status. There's minimal waste. It could potentially be more concise, but the current length is reasonable and every sentence contributes value.

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 no annotations and no output schema, the description must do more work. It covers the core purpose and draft status, but for a mutation tool that creates a new document based on an existing one, it doesn't disclose whether the original delivery note remains unchanged, what preconditions apply (e.g., must be issued, not already storno'd), or what the response/return format looks like. This is adequate but leaves meaningful gaps.

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%, meaning both parameters (uuid and companyId) are already described in the schema. The description refers to 'an existing issued delivery note' which maps to the uuid parameter. However, the description doesn't add detail beyond what the schema provides — it doesn't clarify the companyId override behavior beyond the schema's own text, so it rests at the baseline 3.

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 what the tool does: creates a storno delivery note with negated quantities from an existing issued delivery note. It uses specific verbs ('Create', 'storno') and identifies the resource (delivery note). It distinguishes somewhat from siblings by clarifying it creates a draft rather than issuing immediately, though it doesn't explicitly differentiate from delivery_notes_cancel or delivery_notes_delete.

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 explains the 'when' context — that this is for storno/return operations on an issued delivery note — which implies when it should be used relative to alternatives like delivery_notes_cancel or delivery_notes_create. However, it doesn't explicitly name alternative tools or state when NOT to use this tool, leaving the differentiation implicit rather than explicit.

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