Detect code smells (heuristic)

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

With no annotations provided, the description carries the full burden. It clearly discloses that results are 'HEURISTICS ONLY — hints, never verdicts' and that 'a clean run does not certify good design.' This is meaningful behavioral context beyond the schema. It also implies no side effects (read-only scan), though it doesn't mention return format details or performance limits. The heuristic limitation is the key trait and is well disclosed.

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 three concise sentences, each adding essential information: what it scans, what each finding includes, and the critical heuristic caveat. There is no filler or redundant phrasing. The key info is front-loaded, and the caveat is placed appropriately at the end.

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 the tool has 7 parameters but all are documented in the schema, and an output schema exists, the description doesn't need to detail return values. It effectively communicates the tool's behavior and output characteristics (findings mapped to principles and refactors). It lacks a note on input languages or limitations, but for a static analysis heuristic tool, the description covers the essential operational context.

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%, so the baseline is 3. Each parameter (e.g., maxDepth, maxParams) has a clear schema description. The tool description adds context by mapping the smells to the parameters, but doesn't provide additional syntax or interaction details beyond what the schema already offers. It doesn't compensate further because the schema is fully self-explanatory.

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 states a specific verb ('Scan') and a clear resource ('a code snippet'), and lists the exact smells detected (long method, large class, etc.). This clearly distinguishes it from sibling tools like list_catalog, explain_concept, and scaffold_pattern, which are unrelated. No ambiguity about what the tool does.

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 implies usage context by stating its function and the heuristic caveat, but it does not explicitly state when to use this tool over alternatives or when not to use it. There is no mention of prerequisites (e.g., supported languages, input size limits) or exclusions. The sibling tools are sufficiently different that use is implied, but not explicitly guided.

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