compose_wait

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds valuable behavioral context beyond that: the blocking-until-timeout behavior, the subprocess kill on timeout, the fact that exit codes are on stdout, and the nuanced exception behavior (does not raise on non-zero CLI exit but raises on missing plugin or timeout). This is rich, non-obvious behavior that an agent needs to know. It doesn't describe the full return dict, but the Returns section covers the key fields.

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 well-organized: a one-sentence core behavior, a use-case paragraph with warnings and sibling routing, an exception note, and a compact Args list. Every sentence earns its place. The most important behavioral facts (blocking, timeout, exit codes) are front-loaded before the parameter details.

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 blocking wait tool with 5 parameters and no output schema, the description is complete. It covers the blocking semantics, timeout behavior, exit-code location, exception behavior, parameter meanings, and return dict shape. The sibling routing (container_wait, service_wait) closes the last ambiguity. There is no output schema, so the Returns section is necessary and present. Nothing an agent needs to call this correctly is missing.

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%, so the description must compensate for all five parameters. It does: services (one or more, at least one required), project_dir (default server cwd, copied to target host if no local plugin), files (explicit compose file paths, repeatable -f), project_name (override), timeout_seconds (default 300s). The project_dir note about copying to the target host is genuinely useful context beyond the schema. The only minor gap is that files doesn't mention the default behavior when omitted, but the schema's default:null plus the project_dir note covers the common case.

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 a specific verb and resource: 'Block until the named service containers stop, then return their exit codes.' It clearly distinguishes this from sibling tools by naming container_wait and service_wait as alternatives for different scopes. The one-shot/batch use case is stated explicitly, so an agent can tell this apart from compose_stop, compose_run, or container_wait without opening schemas.

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 gives explicit when-to-use guidance: 'For one-shot / batch services' and warns that long-running services block until timeout. It names alternatives directly: 'For a single container use container_wait; for swarm services use service_wait.' It also states when it does not raise (non-zero CLI exit) versus when it does (missing plugin or timeout), which is essential for correct invocation.

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