diadoc_delete_raw

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

Annotations already mark this as destructive and non-read-only; the description adds useful context by requiring both confirmation flags and stating that the operation is DELETE-only. The return envelope ({"ok": true, "status", "data"} or error envelope) further clarifies expected behavior. No contradiction with the annotations is present.

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 front-loaded with the dangerous delete warning and the required confirmation flags, then lists parameters compactly. It is slightly redundant because the args list repeats schema parameter names, but the added semantic hints, such as path format and host override behavior, justify 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?

For a powerful raw delete tool, the description covers the critical operational requirements: path format, method, confirmation flags, host override, and response envelope. Given that an output schema exists and annotations already signal destructive behavior, nothing essential is missing for an agent to invoke it safely.

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?

With 0% schema description coverage, the description carries the parameter-documentation burden and does so reasonably well: path must begin with '/', method should be DELETE, host overrides the default, and both confirmation flags must be true. The query and body descriptions are thin ('query-string parameters', 'JSON request body'), which keeps this from a perfect score.

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 opening phrase 'Delete data at ANY path, including paths not in the catalog' states a specific verb, resource, and scope. This clearly distinguishes the raw delete tool from catalog-scoped siblings like diadoc_delete_method, while the DELETE-only and confirmation-flag requirements reinforce its identity.

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 makes the intended use explicit: delete arbitrary paths, including ones outside the catalog. It also provides essential usage constraints by requiring confirm_write=true and i_understand_this_modifies_data=true. However, it does not explicitly state when to prefer a sibling tool or when not to use this one.

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