compose_kill

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

While annotations already mark destructiveHint=true, the description adds substantial behavioral context: the immediate kill with no grace period, the non-raising behavior on non-zero CLI exits, the specific exceptions that still raise (missing plugin, timeout), and the project_dir copy-to-host behavior. These traits are not captured by the annotations and are crucial for an agent to predict side effects.

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 efficiently structured: purpose in the first line, behavioral caveats in a short second paragraph, then a compact Args list and a Returns line. Every sentence adds information; there is no filler. The front-loading of purpose and the most important caveat ('prefer compose_stop') makes it easy for an agent to parse.

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 tool with 6 parameters and no output schema, the description is complete. It explains all parameters, return values (dict with returncode/stdout/stderr/truncated), the destructive nature, and the nuanced CLI-exit behavior. Combined with the annotations, an agent has everything necessary to invoke the tool correctly and interpret results.

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?

With schema description coverage at 0%, the description fully compensates by documenting all 6 parameters in the Args section. Each parameter gets an explanation beyond the schema's type/default: 'services: Restrict to these services (default: all)', 'signal: Signal to send (default "SIGKILL"; e.g. "SIGTERM", "SIGHUP")', and 'files: Explicit compose file paths (repeatable, `-f`)'. This adds real semantic value.

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 clear, specific verb phrase: 'Send a signal to a compose project's containers (default SIGKILL).' It explicitly identifies the resource (compose project containers) and the action (send signal), and it differentiates from the sibling compose_stop by noting the default signal and the 'prefer compose_stop' guidance. This leaves no ambiguity about what the tool does.

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 states when to use this tool ('Immediate, with no grace period') and when to prefer an alternative ('prefer `compose_stop` for a clean shutdown (stop signal, then kill after a timeout)'). It also provides a behavioral guideline for error handling: 'Does not raise on a non-zero CLI exit ... inspect `returncode`/`stderr` in the result.' This is explicit when/when-not guidance with a named sibling.

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