smell_detect_feature_envy

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys read-only analysis by inference ('Find methods...') but does not state what the tool returns, whether it writes any output, which languages it supports, why api_key exists, or any analysis limitations. A one-sentence description is insufficient for a scanner with no output schema.

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?

A single sentence with zero filler, front-loaded with the action verb and the precise detection criterion. Nothing could be trimmed without losing meaning.

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?

For a tool with no annotations, no output schema, and an undocumented api_key parameter, one sentence is not enough. An agent cannot tell what the tool returns (a report? a list of locations?), whether it modifies the codebase, what language projects it supports, or whether api_key is mandatory — all gaps that matter 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 coverage is only 50% (api_key has no description in the schema), so the description should compensate for the undocumented parameter — it does not. The description adds no meaning beyond what the schema already says about 'directory' and is silent on api_key's purpose or whether it is needed for analysis.

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 ('Find'), a specific resource ('methods'), and a precise criterion ('use more data from other classes than their own') — the textbook definition of feature envy. This clearly distinguishes the tool from sibling smell detectors like smell_detect_long_methods and smell_detect_god_classes.

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?

No guidance is given on when to choose this tool over its smell_detect_* siblings, or on how it relates to smell_refactor_plan. The staging context 'scan this directory' is implied by the directory parameter, but there are no explicit conditions, exclusions, or alternative routing.

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