Diagnose and fix Carve

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

The description claims the tool can 'optionally apply selected safe fix IDs,' which is a mutating behavior, while annotations set readOnlyHint=true. This is an annotation contradiction, so the behavioral disclosure cannot be trusted. It also leaves ambiguous whether 'apply' means returning a modified source or persisting changes.

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?

Two short, efficient sentences with the main action front-loaded and no filler. The safety clause about writer-review fixes is concise and earns its place as a behavioral guardrail.

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?

This is a multi-step diagnose-and-fix tool, but the description omits the meaning of `platforms`, does not define 'safe fix IDs,' and gives no routing guidance relative to sibling tools. The presence of an output schema helps, but the missing parameter semantics and the annotation contradiction leave the description incomplete.

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 documents only `source` (coverage ~33%), and the description adds meaning only for `applyFixIds` via 'selected safe fix IDs.' The `platforms` parameter is entirely unexplained in both the schema and description, and the description does not define what a fix ID is or how to obtain one.

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 opens with a clear action sequence—diagnose Carve source, propose bounded fixes, and optionally apply selected safe fix IDs—and names the target resource. This gives the tool an identifiable identity distinct from lower-level siblings like carve_parse, carve_lint, or carve_format.

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 workflow: only selected safe fix IDs are applied, and writer-review fixes are never applied automatically. However, it never names alternatives or states when to prefer this tool over carve_apply_reversible_ast_patch or carve_plan_ast_edit, so the usage context is mostly implicit.

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