ecosystem_deep_review_request

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

With no annotations provided, the description carries full burden—and it delivers richly. It discloses the async nature (queued vs running), the derived status column behavior change, the watchdog auto-fail mechanism with timeout_minutes, and the external dependency on the Leader spawning a sub-agent via CC Agent tool. This is exceptional behavioral transparency for an async mutation tool.

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 dense but efficiently organized—one opening sentence stating the core action, followed by a detailed paragraph covering secondary behaviors. Every sentence earns its place: the queuing mechanism, status derivation, watchdog timeout, and Leader responsibility are all relevant for correct invocation. No waste or redundancy.

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?

This is a complex async tool with side effects, a background process, and external dependencies. The description covers all these aspects: queueing semantics, status derivation, timeout auto-fail, and the Leader/spawn dependency. The interaction between stage_status and derived status is explicitly clarified. Output schema exists, so return values don't need explanation. Completeness is high for this complexity level.

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 the schema already documents all 4 parameters. The description adds context for repo_id (target of the review) and the timeout_minutes mechanism (auto-fail), but does not add new semantic meaning for agent_id or priority beyond what the schema already states ('Optional pre-assigned agent identifier', 'medium/high/critical'). Baseline 3 is appropriate when schema does 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 is highly specific: 'Queue a deep-review for a repo and return the dispatch prompt.' It names the exact resource (EcosystemDeepReview row queued on the funnel), the action (queue), and the return value (dispatch prompt). It clearly distinguishes from siblings like ecosystem_deep_review_status/list/cancel by being the only request/creation tool.

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 clearly explains the queueing workflow, the derived status fields, the background watchdog behavior, and the timeout handling. However, it does not explicitly state when NOT to use this tool or name an alternative (e.g., ecosystem_deep_review_request_batch for batch requests, or shallow review tools). The Leader-responsibility note gives useful context on the distributed workflow.

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