CodexPro Supertool

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

Annotation Contradiction: The description explicitly says this is a 'stable wrapper' and instructs calling read-only tools like search_project and read_many_files, yet annotations declare destructiveHint=true and readOnlyHint=false, implying it is a dangerous mutating tool. The description frames it as a safe routing layer for hidden actions, which conflicts with the destructiveHint. The description does not disclose any mutation or destructive behavior that would justify destructiveHint=true.

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 taut sentences with zero waste. It front-loads the purpose, immediately gives actionable guidance on what to call instead, and closes with a mode constraint. Every sentence earns its place.

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 wrapper tool that delegates to hidden actions, the description reasonably directs agents away rather than documenting each hidden behavior. Output schema and full param coverage exist. However, given the destructiveHint=true annotation, the description should have clarified what destructive behavior may occur, since the visible-tool comparison doesn't account for hidden specialist actions it wraps. This gap prevents a higher score.

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 100%, so the schema documents both parameters (action and args). The args description ('Same shape as the wrapped CodexPro tool') adds useful context about nesting, and action points to list_actions. The description itself doesn't elaborate further, but baseline 3 is appropriate given full schema coverage and the extra 'same shape as wrapped tool' note adds some value.

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 this is a 'stable wrapper only for hidden specialist actions' and explicitly names the visible tools (search_project, read_many_files, apply_patch_bundle, run_validation, show_changes) that should be called directly instead. This distinguishes it from sibling tools like write, bash, task_complete, etc.

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?

Exceptional guidance: it explicitly tells agents to call visible tools directly ('Call visible tools such as...directly') and warns that wrapping visible actions 'adds avoidable routing failures'. It also notes it cannot call tools disabled by the current mode, which is a clear usage constraint.

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