generate_fix

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, yet it only states what the tool does, not how it behaves. It does not mention whether it modifies files, returns a suggestion, requires network access, or has any side effects. The description also omits the existence of fallback JSON parameters (findingJson, candidateJson) and their interaction with structured inputs, leaving the agent guessing about important behavioral details.

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 with no filler. It front-loads the core action and lists the key inputs. It is not structured with headings or details, but for a tool with a simple one-line purpose, this is appropriately sized. Minor deduction for not being broken into more scannable parts, but efficiency is strong.

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 has 6 parameters, nested objects, no output schema, and no annotations, yet the description offers only a high-level statement. It does not explain the output format, the relationship between required and optional parameters, the fallback mechanism, or any prerequisites (e.g., needing a verified finding). An agent cannot fully understand how to invoke or interpret the result from this description alone, making it incomplete for the tool's complexity.

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 100%, so the baseline is 3. The description adds meaning by clarifying that the candidate contains line range and snippet ('candidate line range, actual snippet'), which the schema itself does not provide. However, it does not explain the purpose of findingJson/candidateJson fallbacks or why only filePath is required when the description implies all three sources are needed. No explicit conflict, but the description adds modest value over the schema.

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 states the tool's purpose: generating a contextual fix based on specific inputs (candidate line range, actual snippet, verified finding). It uses a specific verb ('generate') with a clear resource ('fix') and names the key inputs, distinguishing it from siblings like generate_poc or generate_report. The purpose is unambiguous and non-tautological.

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 provides no guidance on when to use this tool versus alternatives or any prerequisites (e.g., needing a verified finding from verify_finding first). It does not mention conditions that would select this tool over siblings, nor does it state any exclusions or dependencies. An agent must infer the workflow context from the tool's name and parameters alone.

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