brc_delete_sales_credit_note

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

With no annotations, the description carries full burden. It fully discloses the behavioral pattern: the mandatory preview step, the requirement for explicit user confirmation, and that a preflight call is not confirmation. It does not cover potential side effects (e.g., irreversibility or permissions), but the core interaction is well-explained.

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 detailed but necessary to explain the confirmation workflow. Every sentence serves a purpose; no fluff. Could be slightly shorter, but the complexity warrants the length.

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 covers the confirmation mechanism well but lacks details on what happens after deletion (e.g., success response, error handling, whether it's a soft or hard delete). For a destructive operation, more behavioral context would be helpful.

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 75%, so baseline is 3. The description adds significant value for the confirmWrite parameter by explaining its semantics and the two-step process. It does not explain id or companyName beyond the schema, but the schema already has adequate descriptions for those.

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 action ('Deletes a BRC sales credit note by id') and distinguishes this from other operations by specifying the unique timestamp confirmation process. It is specific and unambiguous.

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 explicitly details the two-call workflow: first without confirmWrite to get a preview, then with confirmWrite only after user confirmation. It warns against treating preflight as confirmation. However, it does not compare to alternative deletion methods or explicitly state when not to use this tool.

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