Sync the code index

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so admirably. It states that the operation is incremental by default, only changed files are re-chunked/re-embedded, an unchanged tree is a fast no-op, and auto-sync already occurs in the background. It also covers cold-start behavior (build from scratch, keyword search live in seconds, vectors backfill) and what a full=true does. This is rich, honest behavioral context with no contradictions.

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 compact but information-dense, with each sentence contributing distinct behavioral or usage detail. It front-loads the core purpose in the first clause, then systematically covers incremental behavior, auto-sync, cold-start, the full flag, and return value. There is no filler or repetition, making it an efficiently structured paragraph.

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 no annotations and no output schema, the description covers all the essential aspects a calling agent needs: default behavior, when to call, how to force a rebuild, cold-start timing, return information, and the path parameter's role is covered by the schema. It is complete for a synchronization tool and leaves no significant ambiguity about invocation or expected results.

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 100%: both parameters (full and path) are described in the input schema. The description adds a bit by saying 'Pass full=true to force a rebuild from scratch,' but that essentially restates the schema's 'Force a full rebuild instead of an incremental sync.' Since the schema already documents meaning, the description adds marginal value beyond it, keeping the score at the baseline of 3.

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 and resource: 'Bring the index up to date with the working tree.' It immediately distinguishes itself from sibling tools (search, sql) by focusing on index synchronization. The description also explains the core behavior (incremental by default, full rebuild option) and makes it unmistakable what the tool accomplishes.

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 gives clear usage context: 'call this freely after edits' and notes that the server auto-syncs in the background 'as queries arrive.' This tells the agent when to invoke the tool, though it doesn't explicitly name alternatives or state when not to call it. The guidance is strong enough that an agent knows to use this after modifications, and it gets a 4 rather than a 5 because it lacks explicit 'use X instead' exclusions.

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