delete_document

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

With no annotations, the description fully carries the burden of behavioral disclosure. It clearly states that the tool deletes the document and all associated data (chunks, embeddings, etc.) and notes the optional deletion of the PDF file in MinIO. This effectively conveys the irreversible and broad impact.

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 relatively concise, mixing Chinese and English. It includes a clear heading ('删除指定文档') followed by bullet-like paragraphs. However, it could be slightly more structured with explicit sections for parameters and returns, though the current format is functional.

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?

Given the tool's complexity (delete with cascading effects) and the presence of an output schema (implied from 'Has output schema: true'), the description adequately covers the deletion behavior, optional PDF removal, and return information. It omits details like error handling or authorization requirements, but remains complete for a typical delete operation.

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?

The input schema provides no descriptions for its parameters (coverage 0%). The description adds significant value by explaining each parameter in the Args section, including the doc_id as the document identifier and also_delete_object as an optional boolean to control PDF deletion. This fully compensates for the schema's lack of 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 clearly states the tool's purpose: deleting a document and all associated data. It specifies the resource ('document') and the action ('delete'), and distinguishes from siblings like get_document or list_documents by emphasizing the destructive nature.

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?

No explicit guidance on when to use this tool versus alternatives. While the description implies it's for deleting documents, it does not mention conditions, prerequisites, or refer to sibling tools (e.g., when to use update_document instead).

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