remove_folder

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

With no annotations, the description takes full responsibility for disclosing behavior. It states that all index data (files, chunks, search index) is purged, that on-disk documents are untouched, and that in-progress background indexing is cancelled. It also provides the return tuple. This is exemplary disclosure for a mutating tool.

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 three sentences, with the main action in the first sentence and essential clarifications in the second and third. Every sentence contributes useful information and there is no fluff. The structure loads the primary purpose first and then adds nuance, making it easy for an agent to parse.

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 simple tool with one parameter and an output schema (not shown in detail), the description covers the core behavior, side effects, and return value. It does not address error handling or idempotency, but given the tool's simplicity and the existence of an output schema, the description is reasonably complete. A small gap is the lack of any note about the folder needing to be registered, but that is implied by 'Unregister'.

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 only parameter, 'path', has no schema description (0% coverage) and the tool description does not elaborate on the expected format, whether it must be absolute, or whether it needs to match the exact path used in add_folder. The description only uses the word 'folder', which is nearly synonymous with 'path'. Thus it provides no added semantic value.

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 opens with a specific verb phrase 'Unregister a folder and purge all its index data' and enumerates exactly what is purged (files, chunks, search index). It also clarifies the non-destructive effect on disk data, which distinguishes it from a delete operation. The tool name alone would be ambiguous, but the description eliminates that.

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 the tool is for removing a folder from the index, and explicitly points to list_folders for listing registered folders, giving context. It also warns that on-disk documents are untouched, which tells the agent not to use this tool if physical deletion is intended. However, it does not explicitly name alternatives like reindex or add_folder for comparison, so it stops short of full differentiation.

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