compose_run

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral details beyond this: it always disables TTY, defaults to detached mode with container removal, and creates a new container for each run. It does not mention auth/error behavior, but the disclosure of the --rm default and the new-container semantics is significant and non-contradictory.

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-organized: a one-sentence purpose, two sentences of behavioral context, a complete args list, and a return type. Every sentence adds value and there is no redundant or fluff content. The structure is front-loaded with the most important information.

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?

With no output schema, the description specifies the return dict with fields (returncode, stdout, stderr, truncated). It covers all parameters, key behavioral defaults, and the MCP-specific TTY constraint. Minor gaps include not elaborating on what 'truncated' means or how detached mode affects stdout/stderr, but these are acceptable given the overall richness.

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?

Despite 0% schema description coverage, the description contains a complete 'args:' section explaining all 13 parameters in meaningful terms. Examples include noting that command runs in exec-form unless a shell is invoked, project_dir is copied if no local plugin, and timeout_seconds defaults to 600. This fully compensates for the schema's lack of descriptions.

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+resource: 'Run a one-off command against a compose service.' It also explicitly differentiates from compose_exec by stating that it starts a NEW container rather than running inside an existing one, making its purpose unambiguous.

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 clear behavioral context: always passes -T, defaults to detached with --rm, and explicitly contrasts with compose_exec. It implies the intended use case (one-off commands in a new container) but does not explicitly list alternative tools or say when not to use it, falling just short of a 5.

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