delivery_notes_update

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 the destructive replacement behavior ('Replaces all line items with the provided array') and status limitations, which are the two most important behavioral traits. It does not state whether the update is reversible, whether a version/draft is created, or what response to expect, but given no output schema and no annotations, the disclosed constraints are valuable. Lacks mention of irreversible effects like losing existing line item references.

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 short sentences, zero waste. Front-loads the purpose, then the critical status constraint, then the destructive line-replacement behavior. Every sentence earns its place with meaningful information.

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?

For a 42-parameter mutation tool with no annotations and no output schema, the description covers the essential semantics (update, status limits, line replacement) but omits some context: whether the note number/series is immutable after issue, consequences for already-issued notes, and any return value/confirmation. The complexity is high, and richer behavioral context (e.g., e-Transport field validation interplay with replacement) could be stated. Adequate but not comprehensive.

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 every parameter is documented in the schema. The description highlights the crucial line-replacement semantic ('Replaces all line items with the provided array'), which is not evident from the schema alone. With full coverage, the baseline is 3 and the added 'replaces' note is useful context but doesn't go beyond the key semantic.

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?

States clear verb+resource ('Update an existing delivery note'), plus a critical behavioral constraint ('Delivery notes in draft or issued status can be updated') and the key replacing semantics ('Replaces all line items with the provided array'). Clearly distinguished from siblings like delivery_notes_create, delivery_notes_delete, delivery_notes_issue.

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?

Specifies status prerequisites (draft or issued). Does not explicitly contrast with delivery_notes_create for creating new notes vs updating existing, nor state when NOT to use this (e.g., issued notes requiring storno instead). The status constraint provides clear context but no explicit exclusions or named alternatives.

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