pro_repair

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavior: the default plan mode mutates nothing, and apply can fail on stale state, implying the plan must be fresh. 'No guessed dimensions, equations or mates' also signals the tool will not invent values, which shapes how the agent should supply inputs. It stops short of saying what gets destroyed on apply.

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?

Three short sentences, front-loaded with the plan-first constraint, with no filler. The closing fragment 'No guessed dimensions, equations or mates' is terse to the point of being cryptic, but the structure itself is efficient.

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 destructive, six-parameter tool with a conditional if/then/else schema and no output schema, so the description should do heavy lifting. It covers the plan/apply safety model but leaves every parameter and the returned plan artifact undocumented, which is not enough 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 description coverage is 0% across six parameters, so the description carries the burden and largely fails it. It only clarifies 'action=apply' and gestures at a plan handle; document_path, components, the reconnect/resolve/rebuild action enum, and result_view are all unexplained, as is the conditional plan_id-vs-document_path 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 states a plan/apply repair workflow with a specific verb ('repair') and safety framing, but never says what is being repaired (components? mates? features?) or what the repair operations are. Against siblings like rebuild, pro_diagnose, pro_validate_design and pro_connection_doctor, an agent cannot tell from this text which tool addresses its problem.

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?

'Plan repairs first without changes. Only a separate action=apply executes that plan' gives a clear sequencing rule for using this tool. However, it gives no guidance on when to reach for pro_repair versus pro_diagnose, rebuild, or pro_connection_doctor, and no prerequisites for the apply step beyond 'stale-state checks'.

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