Clear Active Index Safely

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

Annotations already indicate destructive behavior, and the description adds valuable context: the action is recoverable via backup, and execution requires a token. It does not detail what happens to the current index beyond 'move' or how token matching works, but it goes beyond the annotations.

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?

Two concise, front-loaded sentences deliver the essential purpose and a safety requirement without any filler. Every word adds value.

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 is sufficient for basic invocation but leaves gaps: how to obtain the 'matching token,' what preview outputs, and how restore relates to the backup. Sibling tools imply the restore path, but the description does not explicitly connect them.

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 description coverage is 0%, so the description must compensate. It explains the action parameter through 'preview or move' and the confirmationToken through 'execution requires a matching token.' It does not explicitly bind these to parameter names or describe token format, but it gives meaningful semantics for both.

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 operation: moving the active index into a recoverable backup, with preview and execute modes. It is distinguishable from siblings like rag_restore_index and rag_list_backups, though it does not use the word 'clear' explicitly.

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 implies use when clearing the active index and notes that execution requires a matching token, but it does not explicitly contrast with alternatives or state when not to use the tool. The preview/execute distinction provides some usage context.

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