analyze_code_quality

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

No annotations are provided, so the description must carry the full burden. It hints at behavioral traits (slim vs full rescan, session-based short-circuiting) but doesn't disclose what 'slim findings' means precisely, whether this mutates state, what the score is based on, or any side effects. 'Slim findings + score' is telegraphic and leaves important behavioral details unexplained.

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 a single tight sentence that front-loads the core purpose and includes a useful qualifier about the slim-versus-full behavior. It's efficient with no fluff, though slightly telegraphic.

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?

This is a moderately complex analysis tool with 3 parameters, no output schema, and no annotations. Given the sibling ecosystem includes many specialized analyze_* tools, an agent needs clearer guidance on what this covers vs the other analyzers. The description doesn't explain the score semantics, return shape, or how 'slim' differs from the full review_project output, leaving significant gaps for correct invocation.

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 0%, so the description must compensate for 3 undocumented parameters. The description mentions sessionId and path contextually (session-based vs path-based) but says nothing about the 'limit' parameter at all. It adds some meaning for two params but entirely misses the third.

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 uses a specific verb and resource (analyze code quality from a review_project session or path) and clearly states this produces 'Slim findings + score'. It distinguishes itself from a full rescan. However, it doesn't explicitly mention sibling tools like analyze_architecture, analyze_complexity, etc., so some differentiation ambiguity remains.

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 conveys that sessionId is the slim path ('not a full rescan when sessionId is set') versus path-based analysis. However, it doesn't explicitly state when to choose this over siblings like analyze_architecture, analyze_complexity, or analyze_testing, nor does it explain when to use path vs sessionId mode in detail.

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