Delete Document

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

No annotations are provided, so the description fully discloses the destructive nature of the operation, states that the source file is untouched, and warns that deletion is permanent and chunk_ids will stop resolving. It also explains that re-ingesting rebuilds the document, giving a complete behavioral picture.

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 concise, well-structured, and every sentence adds meaningful information: the primary effect, the scope, the typical use case, the exception for edits, and the permanence/consequence. No fluff or redundancy.

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 simple one-parameter schema and its rich explanatory description, the description is fully complete for an agent to decide when and how to use it. The presence of an output schema also means return-value details are not required in the description.

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 covers 100% of the single parameter (document_id) with a description referencing get_document_outline's library listing. The description does not add further param-specific meaning, but the schema already provides the necessary context, so a baseline of 3 is appropriate.

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 action ('Remove a document from the index') and lists exactly what is removed (chunks, full-text entries, vectors). It also distinguishes this from sibling tools like ingest_document by explicitly noting that re-ingesting replaces versions, so delete is only for mistaken ingestion.

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?

Provides explicit when-to-use guidance ('Use it to drop something ingested by mistake') and an exclusions ('an edited file does NOT need this, because re-ingesting one already replaces the version it supersedes'). This clearly directs the agent away from unnecessary deletion.

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