index_update

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

Annotations declare a non-read-only, non-idempotent mutation, and the description usefully adds that claims whose files changed 'become stale' — a real behavioral consequence. However, it never explains what re-indexing actually rebuilds or whether concurrent runs are safe, and the listed modes are unexplained, so it is adequate rather than rich.

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 dense sentences with the core action front-loaded and no filler. The parenthetical and mode tail are slightly compressed/awkward but not wasteful.

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 zero-parameter tool with annotations covering safety and no output schema, the description covers purpose, trigger, effect on claims, and mode options — enough for correct invocation. The unexplained mode list and schema mismatch are the only gaps.

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 schema declares zero properties, which would baseline at 4, but the description introduces a 'mode' parameter with enum values (noop | incremental | full | first_scan) that do not exist in the schema — a confusing mismatch rather than genuine parameter elucidation.

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?

States a specific verb+resource ('Re-index after editing files') and adds scope context (first scan on a never-scanned folder). It does not differentiate itself from siblings like analyze or code_check, which it plausibly overlaps with, so it stops short of a 5.

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 trigger is implied ('after editing files') and the parenthetical hints at the first-scan case, but no alternative tool is named and there is no explicit when-not-to-use guidance. Usage is inferable but not spelled out.

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