cancel_consignment

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals key side effects: line mode 'undoes the disposition' and whole-document mode 'books/moves nothing.' It also notes that reason is recorded and that confirm=true is required, which goes beyond what the schema alone conveys.

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 compact and well-structured, front-loading the primary purpose and using line breaks to separate the two modes. Every clause adds operational meaning—conditions, side effects, and required parameters—with no filler.

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 tool with two distinct behaviors, no annotations, no output schema, and zero parameter schema descriptions, the description covers the main scenarios, preconditions, and side effects well. Minor gaps remain around the exact form of `consignment_out` and what the tool returns or confirms after success.

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 0%, so the description must compensate. It explains the `line` parameter's dual behavior, the `reason` requirement, and the `confirm` requirement. However, `consignment_out` is not described beyond the tool name, and the exact format of `line` is left implicit.

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 states a specific verb and resource ('cancel a consignment') and precisely distinguishes two modes: canceling one shipped line vs. canceling the whole DRAFT document. This makes it clearly distinct from sibling tools like cancel_order and frappe_cancel_document.

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 gives explicit conditions for each usage mode: line cancellation is 'only reachable pre-invoice,' and whole-document cancellation applies to a 'never-shipped staging record.' It lacks an explicit statement of when not to use this tool versus named alternatives, but the conditions are clear enough for an agent to route correctly.

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