xdc_auto_fix

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

With no annotations provided, the description fully covers the tool's behavior: dry-run preview mode, backup creation per file, .bak only keeping the latest version before write-back (with sed -i.bak semantics), insertion logic for IOSTANDARD after PACKAGE_PIN, and skipping CLOCK_NO_PERIOD when the board is unknown. It also states which issue types are intentionally not handled, making side effects and boundaries explicit.

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 well-structured with a main purpose, operational notes, explicit inclusion/exclusion lists, and a parameter breakdown. It is concise for the complexity involved, with every sentence contributing to understanding or safe usage. The use of bullets and clear headings (e.g., '只修', '绝对不碰') aids readability.

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 tool's complexity (mutating files, multiple parameters, safety implications) and lack of annotations, the description is exceptionally complete. It explains side effects (backup, overwrite), edge cases (unknown board), and provides a safe workflow. The presence of an output schema means return-value details are not required, and the description covers all other necessary contextual information.

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 0%, but the description thoroughly explains every parameter: xdc_paths (list, defaults to session project), board (supported values and fallback to LVCMOS33), dry_run (preview vs write-back), and session_id (used only when xdc_paths is omitted). It adds default values and cross-parameter dependencies, fully compensating for the lack of schema descriptions.

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 it automatically fixes self-safely fixable issues in XDC files, specifically MISSING_IOSTANDARD and CLOCK_NO_PERIOD. It distinguishes itself from sibling tools by explicitly limiting its scope to these two issue types and stating it never touches conflict-related problems (PIN_CONFLICT, DUPLICATE_PORT, etc.), which require manual intervention.

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 explicit when-to-use guidance: it only fixes the two listed issue types and absolutely avoids conflict categories. It also gives a clear workflow: use dry_run=True to preview, then dry_run=False to apply. However, it does not explicitly name sibling tools as alternatives (e.g., xdc_lint for broader linting), so it misses the 'alternatives' part of the top tier.

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