codex_repair_issue

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

Annotations are empty, so description carries the burden. It mentions an audit trail (before/after audit) and that unsafe actions require force=true, but lacks details on destructiveness, rate limits, or side effects. Some transparency added, but minimal.

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?

A single sentence is very concise, but for a 15-parameter tool, it is too brief. Could use structured bullet points for parameter hints. Under-specified rather than concisely informative.

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 complexity (15 params, 1 required, enums, output schema exists), the description is incomplete. It fails to describe the allowed action meanings, the purpose of optional parameters, or any input guidance beyond force. Output schema exists, so return values are covered, but inputs are not.

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%. The description only hints at the force parameter semantics indirectly. It does not explain the action enum, diagnosis_id, thread_id, or other parameters. The parameter meaning is largely absent.

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 runs allowlisted repair actions with an audit, distinguishing it from sibling tools like codex_interrupt_turn or codex_restart_app_server. The verb 'run' and resource 'MCP/Codex repair action' are specific.

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?

It gives a condition for unsafe actions requiring force=true, but does not provide when-to-use vs alternatives (e.g., when to use this vs codex_interrupt_turn for similar repairs). No explicit exclusions or alternative tool names.

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