compose_unpause

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

The annotations only indicate that this is not read-only and not destructive; the description adds meaningful behavioral detail: processes continue from where they were frozen without restart, a non-zero CLI exit does not raise an exception, and project_dir may be copied to the target host when no local plugin exists. This goes beyond the annotations and helps the agent predict side effects and error behavior.

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 well-structured and front-loaded: the core action appears first, followed by sibling distinctions, error behavior, parameter definitions, and return type. Every sentence carries useful information and no filler or redundant restatement is present.

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 the tool has no required parameters, no output schema, and moderate complexity, the description is complete: it documents all parameters with defaults and behavior, explains return values, distinguishes related tools, and discloses error-handling quirks. There is no missing information an agent would need to invoke it correctly.

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%, but the description compensates fully by explaining all four parameters: services restricts to given services (default all), project_dir defaults to server cwd and may be copied to the target host, files accepts repeatable compose file paths via -f, and project_name overrides the project name. This adds meaning the raw schema alone does not convey.

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, unambiguous statement: 'Unpause the containers of a compose project (resumes paused processes).' It also distinguishes the tool from closely related siblings by calling itself the reverse of compose_pause and naming compose_start as the counterpart for stopped containers. An agent can immediately tell what the tool does and how it differs from similar operations.

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 situates this tool relative to alternatives: use it to resume paused containers ('Reverse of compose_pause'), and use compose_start instead when containers are stopped. It also clarifies what does and does not raise an error, telling the agent how to interpret non-zero exits by inspecting returncode/stderr. This gives clear, actionable selection guidance.

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