Run Acceptance

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

Annotations declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, which cover the mutation/execution safety profile. The description adds useful async behavior context (persistent local tasks returning run ids immediately vs synchronous checks). However, it doesn't disclose what happens on failure, cleanup behavior, or whether results are retrievable via read_acceptance_result or acceptance_status, leaving behavioral gaps that annotations also don't fill.

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?

Two sentences, zero filler. Every word earns its place — the first sentence states the core function, the second conveys the crucial async/sync dichotomy that shapes agent expectations. No redundancy with schema or annotations.

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 an output schema exists (so return values are documented), rich annotations, and 100% schema parameter coverage, the description provides adequate context. It covers the key decision (sync vs async execution) that an agent needs to know before invoking. Small gap: doesn't mention how to retrieve results or check status for long-running tasks, though sibling tools (acceptance_status, read_acceptance_result) imply this flow.

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 100%, so all 8 parameters are documented in the schema. The description adds value by explaining the async/sync behavioral distinction which maps to execution_mode semantics, but mostly relies on schema descriptions that are already quite detailed (e.g., workspace_id auto-binding, conversation_id injection, stale generation rejection). This is a baseline-3 case where the schema carries the heavy lifting.

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 a specific verb+resource: 'Run commands from .codexpro/acceptance.yml'. It identifies which profiles run synchronously vs asynchronously, distinguishing this tool's behavior. However, it doesn't explicitly differentiate from sibling tools like run_validation or run_task_status, which could be alternative validation/execution tools.

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 clear context on when each execution mode applies ('Long profiles start as persistent local tasks', 'short checks may remain synchronous'), implying usage for running acceptance tests. However, it doesn't explicitly state when NOT to use this tool or name alternative tools (e.g., run_validation for other validation types), leaving some ambiguity in tool selection.

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