tool_auto_fix

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

No annotations exist, so the description carries the full burden and does well: it discloses the mutation is scoped ('safe, targeted fixers'), explains each fixer's concrete effect, and explicitly flags 'missing_labels' as report-only rather than a mutating fixer. It stops short of stating file backup/reversibility or permission requirements for a tool that edits project files.

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?

Front-loaded with the one-line purpose before the fixer catalog, and the bulleted fixer list earns its length because those names are otherwise undocumented in the schema. The trailing Returns block is redundant-free but slightly verbose against a short signature.

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?

For a 2-param mutating tool with no annotations and no output schema, the description covers purpose, both parameters, fixer semantics, and the return shape (ok/applied/skipped and before/after compile status). Only safety around editing files (backups, partial-failure behavior) is left unstated.

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%, so the description must compensate, and it does: project_path is defined as the absolute project root and fixes as a list of fixer names with a None default meaning 'run all'. Critically, it enumerates the valid fixer names that the schema (which only types them as plain strings) does not constrain, which is the key semantic the caller needs.

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?

States a specific verb+resource+outcome: detect and repair Ren'Py issues then re-compile to verify. The verb 'repair' differentiates it from siblings like tool_lint_project, tool_check_project, and tool_compile_project, which only diagnose or build.

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?

'Runs a set of safe, targeted fixers' and 'If None, runs all fixers' give implied usage context, and the instruction that it re-compiles afterward signals when it fits. However, it never explicitly contrasts itself with the sibling diagnostic tools (lint/check/list_fixers) or states when NOT to auto-fix, leaving the routing decision partly to inference.

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