reindex_codebase

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

With no annotations, description carries full burden. It mentions heavy operation and database creation location, but doesn't disclose whether previous index is overwritten, or potential side effects like file scanning delays.

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?

Three concise sentences: purpose, usage guidance, output location. No redundancy, every sentence 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?

Given output schema exists (though not provided here) and one parameter, the description covers the main effect and usage context. Could mention asynchronicity or prerequisite like directory existence.

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 coverage is 0%, so description must compensate. Only one parameter 'root_path' is referenced in the output path but not described (e.g., must be absolute path, must exist). Lacks sufficient detail for correct invocation.

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?

Clearly states scanning and indexing a directory to build a knowledge graph, with specific output location. Distinguishes from sibling tools that are query-oriented.

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?

Explicitly labels as heavy operation and recommends calling only when codebase changes significantly. No explicit when-not-to-use or alternatives, but context implies infrequent usage.

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