ouroboros_start_execute_seed

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

With no annotations, the description carries the full behavioral disclosure burden. It does disclose key runtime behavior: the tool runs in the background, returns immediately, and delegates to a Task pane in plugin mode with job_id=None. However, it does not state whether the operation is mutating, what side effects or permissions are required, or how idempotency_key interacts beyond the schema. This is partial disclosure, not comprehensive.

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 four sentences, each serving a distinct purpose: core action, monitoring pointers, plugin exception, and shell alias warning. It is front-loaded with the primary behavior and uses no filler words. This is exemplary economy.

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?

Despite 15 parameters and no output schema, the description covers the most important context: the async job model, where to find progress/output, the plugin-mode behavioral shift, and the relationship to the 'ooo' shell command. It does not explain return value structure, but no output schema exists and the job_id/None behavior is disclosed. It is complete enough for a high-complexity tool.

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%, with each of the 15 parameters having meaningful descriptions in the input schema. The tool description itself adds no parameter-specific semantics—it stays at the level of execution mode and monitoring. Per rubric, this hits the baseline of 3.

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 opens with 'Start a seed execution in the background and return a job ID immediately,' clearly identifying the verb (start), resource (seed execution), and immediate outcome (job ID). It also notes it is the handler for 'ooo run' commands, which distinguishes it from a shell command but does not explicitly contrast it with sibling tools like ouroboros_execute_seed. This implicit differentiation prevents a 5.

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 explicitly directs users to 'Use ouroboros_ac_tree_hud for live progress snapshots and ouroboros_job_result for terminal output,' providing clear alternatives for post-start actions. It also warns 'do NOT run ''ooo'' in the shell; call this MCP tool instead,' a concrete when-not instruction. The plugin-mode caveat further clarifies when job polling is unavailable.

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