repair_project_setup

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

With no annotations provided, the description carries the full burden of explaining side effects, but it only says the tool can 'dry-run or repair.' It does not disclose whether repair modifies project files, overwrites compile order, adds/removes files, or requires specific environment state. 'Reconciling' hints at mutation but leaves the actual behavioral impact unclear.

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 compact sentence with no fluff, and the most important distinction ('Dry-run or repair') is front-loaded. It is concise and readable, though for a 12-parameter tool with no schema descriptions it is almost too terse to carry the necessary information.

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?

Given the high parameter count, zero schema descriptions, no annotations, and a tool that can mutate project setup, the description is incomplete. It does not explain when repair is needed, what conditions make dry-run appropriate, what side effects occur, or how the many optional parameters interact. The presence of an output schema lessens the need to describe return values, but the usage context is still underexplained.

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%, so the description must compensate, but it only mentions broad categories like RTL, XDC, sim files, tops, and compile order. It does not explain critical parameters such as defines, simulator, include_dirs, project_path, timeout_s, target_language, or testbench_top, nor does it map described concepts to specific parameter names.

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 uses a specific verb set ('Dry-run or repair') and a clear resource ('Project Mode setup') while enumerating the reconciled artifacts: RTL, XDC, sim files, tops, SystemVerilog file types, and compile order. This makes the tool's role distinct enough from siblings like create_project or update_project_compile_order, though it does not explicitly name a sibling or draw a contrast.

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 guidance on when to invoke this tool versus alternatives such as create_project, update_project_compile_order, configure_simulation, or run_project_audit. The word 'repair' implies fixing an inconsistent setup, but the description never states a precondition like 'use when project setup is stale or mismatched' or 'when dry_run=true only reports issues.'

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