fix_module

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

With no annotations, the description carries the full burden of behavioral disclosure. 'Auto-fix' does imply modification, but the description is silent on side effects, safety, reversibility, or the fact that dryRun is available. It does not tell the agent whether running the tool will rewrite files in place or just report planned changes, which is critical for a mutating tool.

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 concise, front-loaded one-liner that gives the core action and scope. It avoids redundancy, but it also leaves out useful context and reads more like a high-level summary than a tool-use guide.

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?

The tool is a mutation-like fix tool with no annotations or output schema. The description does not disclose side effects, failure modes, what happens when dryRun is false, or what the agent should do after validation. This leaves the agent missing key non-structural information needed to use the tool safely.

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 even though the description adds no direct parameter explanations. The mention of naming conventions, imports, and exports adds slight, indirect context to the `fixes` parameter, but the schema itself already explains the parameters adequately.

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 with resource ('Auto-fix module issues') and names concrete categories (naming conventions, imports, exports), making the tool's purpose clear. It does not explicitly contrast with sibling tools like validate_module or analyze_module, so it gets a 4 rather than a 5.

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?

There is no explicit when-to-use guidance or mention of alternatives such as validate_module or analyze_module. The phrase 'common module issues' implies a use case, but the description never states when a module should be fixed versus validated or generated, so usage guidance is weak.

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