code_index

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

The description goes far beyond the annotations: it discloses the exact skip list (.git, node_modules, virtualenvs, binaries, oversize files, secret blocklist shared with context_pack), that the SQLite index lives OUTSIDE the repo, that embeddings are opt-in with fail-safe host fallback via ASK_FABLE_EMBED_HOSTS, the degraded keyword-ranking behavior, and that it returns file/chunk/embedding counts. It also reconciles destructiveHint=true by clarifying the tool is 'Read-only with respect to the repo' — the destructive action applies only to the index, which it explicitly says it refreshes.

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 long but every sentence carries operational value for a complex tool: workflow, skip rules, storage location, incremental behavior, embedding fallback chain, environment variables, and safety guarantee. It is front-loaded with the primary purpose and the sibling link before detailing behavior.

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 tool with zero required parameters and no output schema, the description is exceptionally complete: it covers prerequisites (embedded host env var), failure modes (degraded keyword search), side effects (index refresh), scope (configured project root), and return value shape (counts). An agent can predict the tool's behavior across success and partial-failure scenarios without needing the output schema.

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 100% — the single `rebuild` parameter is already fully documented in the schema ('Re-chunk and re-embed every file even when its content hash is unchanged (default false: incremental)'). The description's mention of 'Incremental: unchanged files keep their embeddings' reinforces but does not meaningfully extend the schema. Baseline 3 is appropriate since the schema carries the semantic weight.

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 opening sentence names a specific verb ('Build or refresh') and resource ('local code+docs index'), and immediately names the downstream sibling tool `code_search`. This cleanly distinguishes it from the dozens of ask_*/context_* siblings in the tool list.

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 establishes the workflow ('then search it with code_search') and explains when the `rebuild` flag is appropriate versus the default incremental run. It gives clear context for when to invoke the tool, though it never states explicit exclusions or alternative tools for the indexing task itself — which is reasonable since no sibling performs this role.

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