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

With readOnlyHint=false already signaling mutation, the description adds valuable behavioral context: state is session-scoped, index_working_tree pins a short-lived synthetic revision, clear reverts to the default, and there is a 100-file/256KB cap. The disclosure is strong, but the undocumented 'commitSha overrides' claim and lack of clarity about what happens on success reduce full transparency.

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 bulleted operation list is compact, front-loaded with a summary, and contains nearly no filler. The final 'index_working_tree' bullet is dense and slightly run-on, and the unresolved 'commitSha overrides' fragment hurts readability, so it is not quite top-tier.

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 complex stateful tool with no output schema, the description covers invocation preconditions, side effects, failure modes, caps, and interactions with sibling tools well. It is incomplete only around the success/error response contract and the unexplained commitSha reference, leaving some room for agent confusion.

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%, so the baseline is 3, and the description does add meaningful context for branch, baseSha, changedFiles, and deletedPaths (e.g., tracked/indexed requirement, synthetic revision, tool visibility). However, the description explicitly mentions a 'commitSha' override that is absent from the schema, which is a concrete parameter-semantics defect that could mislead an agent.

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 crisp summary ('Session-scoped branch / working-tree overlay') and enumerates three distinct operations with their effects, so an agent can see what the tool does without opening the schema. It loses a point because the phrase 'commitSha overrides' references a parameter that does not exist in the input schema, creating ambiguity about the exact behavior.

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?

It gives concrete preconditions ('Branch must be tracked+indexed... else indexing_in_progress') and names which sibling tools reflect the overlay (find_node/locate/relate) versus those that do not (source, locate mode:semantic). It does not explicitly say when to prefer this over alternative tools, but for a state-overlay tool the operation-specific conditions provide adequate routing guidance.

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