analyze_code_quality

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

With no annotations, the description carries the full burden of behavioral transparency. It does disclose what the tool scans for, including potential security smells, but it does not explicitly state that the operation is read-only, how the complexity estimate is calculated, or whether the path is limited to the current repository.

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?

One clean sentence front-loads the main action and uses parentheticals to scope the analysis. No filler, no repeated schema content, and each phrase contributes useful information.

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 a single required parameter and an existing output schema, the description is nearly sufficient for correct tool invocation. The main gap is broader path-semantics documentation, but this is minor for a one-parameter analysis tool.

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?

The schema only describes a 'path' string with no schema-level description (0% coverage). The description adds that a file's metrics will be analyzed, so path clearly suggests a file target, but it doesn't specify path format, relative-to-root ambiguity, or directory compatibility.

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 specific verb ('Analyze') and enumerates concrete analysis targets: line counts, comment ratio, complexity estimate, TODO/FIXME comments, and hardcoded secrets. This makes the tool's purpose clear and distinguishes it from siblings like read_file and search_code.

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?

Usage is implied: call this tool when code-quality metrics or potential issues in a file are needed. However, that description provides no explicit when-to-use/when-not-to-use guidance and does not compare it with sibling tools such as inspect_pr or check_ci_status.

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