find_high_complexity

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It states results are grouped by file and that complexity is a heuristic, which is useful. However, it does not mention that the operation is read-only, nor does it disclose default thresholds (e.g., max_complexity=15) or result ordering. These omissions leave some behavioral uncertainty.

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 concise sentence that states the core output and grouping. It is front-loaded with the key concept and contains no redundant or filler words. Every word contributes to understanding.

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 simplicity of the tool (3 params, no output schema, no annotations), the description covers the essential behavior: it returns functions/methods meeting a complexity threshold, grouped by file. It does not detail the exact return structure or default parameter values, but those are partly covered by the schema. Overall, it is sufficiently complete for a heuristic-lookup 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 already provides descriptive detail for all three parameters (name, max_results, max_complexity) with 100% coverage. The description adds no extra meaning beyond what the schema specifies; the mention of 'high cyclomatic complexity' aligns with max_complexity but does not enrich parameter understanding. Since schema coverage is high, this is adequate.

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 clearly identifies the tool's purpose: finding functions/methods with high cyclomatic complexity, a specific technical-debt heuristic, and notes results are grouped by file. This distinguishes it from sibling tools like find_long_functions (length-based) and function_metrics (comprehensive metrics). The resource and criterion are precise.

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 a use case (technical-debt detection) but does not explicitly state when to use this tool over alternatives. It offers no guidance on when not to use it, nor does it mention sibling tools like find_long_functions or function_metrics as potential alternatives. The context is clear enough to infer, but explicit guidance is missing.

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