kb2_document_delete

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

No annotations are provided, so the description carries full burden. It clearly discloses the destructive nature (move to trash), the mandatory confirmation flow, the expected-value matching to prevent stale deletions, and the permission requirement. This goes well beyond a simple 'delete' statement.

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 four sentences, front-loaded with the core purpose ('WRITE: move to trash'). Each sentence conveys essential information: operation, preview step, confirmation constraint, and permission caveat. No fluff or repetition that isn't load-bearing.

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 destructive delete tool with no output schema, the description sufficiently covers the full flow: preview, confirmation, expected values, and permission. It mentions the preview return data (expected_title, expected_updated_at), making return behavior understandable. The context of children handling is in the schema, so description need not repeat it.

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% and parameters are already well described in the schema. The description adds value by explaining the two-phase workflow (confirm=false preview then confirm=true) and tying expected_title/expected_updated_at to the preview response, which is not fully captured by individual parameter descriptions.

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 explicitly states 'move a Knowledge Base 2.0 document to trash' (переместить документ Базы знаний 2.0 в корзину), using a specific verb and resource. It is clearly distinguished from sibling tools like kb2_document_create and kb2_document_update, as deletion is a distinct operation.

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 step-by-step usage guidance: first call with confirm=false to obtain and show a preview, then only pass confirm=true after explicit user confirmation in the current dialog with matching expected_title and expected_updated_at. It also notes the webhook deletion right requirement, making when-to-use and prerequisites unambiguous.

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