insert_case

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

With no annotations, the description carries the full burden and delivers real behavioral detail: duplicate labels are rejected, with the PHP-semantics rationale (first match wins, duplicates become dead code), and it explains the anchoring strategy that survives a batch. It omits error/failure behavior and any mention of the allow_secrets parameter's behavior.

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?

Front-loads the action and stays to four sentences, but the prose is stylized ('dead code that looks alive', 'stays stable across a batch the way line numbers do not'), which adds flavor at some cost to scannability.

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?

A mutation tool with no annotations and no output schema gets good rationale-level coverage, but the description leaves allow_secrets and context semantics undocumented and does not state what the caller receives. Adequate, not complete.

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 only 40% (context, file_path, allow_secrets lack descriptions). The description usefully clarifies after_case semantics (anchor must be an existing, stable case label) and hints at instruction usage, which partially compensates, but it says nothing about context or allow_secrets.

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?

First sentence states a specific verb+resource ('Add a branch to a switch'), and the second sentence explicitly distinguishes it from symbol-based siblings by noting a case label is not a symbol so no parser addresses it. The purpose is clear, though the differentiation from insert_symbol is implied rather than named.

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 implied context ('in a router-style file it is the extension point every new endpoint goes through') which suggests when this tool is appropriate. However, it never names the alternative tool (insert_symbol) or states exclusions, so the agent must infer the boundary.

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