code_intel

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

With zero annotations, the description carries the full burden, and it delivers meaningful behavioral disclosure: indexes are automatically created/watched/synced/repaired (no user maintenance), routing is deterministic, auto fans out to at most two backends, and the tool is explicitly not the memory owner nor the correctness authority. It does not disclose failure behavior, latency implications of index rebuilds, or whether repair operations can be destructive, but the disclosed autonomy and boundaries exceed what schemas alone provide.

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?

A dense six-sentence paragraph where every sentence earns its place: purpose, backend routing, autonomous index behavior, explicit-control option, system boundaries, and auto behavior. The core purpose is front-loaded. Slightly long, but justified given 15 parameters, three backends, and zero annotations; no fluff or repetition.

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 highly complex tool (15 params, 12 operations, 3 backends, no annotations, no output schema, no siblings), the description covers the conceptual model well but leaves gaps: it does not explain what each operation (search, diagnostics, impact, references, implementations, etc.) returns or how operations map to backends, and with no output schema the agent must guess at return semantics. Adequate for orientation but not fully sufficient for correct invocation of every operation.

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 53%, so the description must partially compensate. It does add meaning to the backend parameter (which backend serves which task type) and to operation/auto behavior (deterministic routing, two-backend fan-out cap). However, seven params (depth, limit, maxChars, operation, timeoutMs, includeBody, substringMatching) are unconditional in the schema and not clarified in the description; several are self-evident by name, but operation—the core behavior selector—relies on enum values without semantics.

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 names a concrete resource ('local code intelligence and index control plane') and specific verbs ('routes', 'creates', 'watches', 'synchronizes', 'repairs'), and maps each backend to a distinct task (zvec-grep→semantic retrieval, CodeGraph→architecture/call-flow/impact, Serena/LSP→symbol semantics). It is clear and internally differentiated, though the abstract 'control plane' framing and the dual role (intelligence query vs. index maintenance) require careful reading.

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?

Provides clear context: 'Prefer explicit operation when known' tells the agent when to bypass auto, and the description explains the auto default's deterministic routing and two-backend fan-out limit. It also sets boundaries ('Sharpshooter remains the durable memory owner', 'OMP native source/edit/build/tests remain correctness truth') that prevent misuse. No sibling tools exist to name as alternatives, so the lack of explicit exclusions is acceptable.

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