docker_start

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

With no annotations present, the description must fully disclose behavioral traits. It only states 'This changes server state,' which is minimal. It does not describe what happens if the container is already running (error or no-op), whether the call returns immediately or waits for the container to become healthy, permission requirements, or potential side effects. For a mutating tool, this is insufficient.

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 two sentences long with no extraneous words. The first sentence states the purpose, and the second adds a brief behavioral note. It is front-loaded and efficient, earning its place without any filler.

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's simplicity (one parameter, well-defined output schema), the description is still incomplete. It lacks usage guidelines, parameter elaboration, and behavioral context beyond a minimal state-change note. The output schema exists but is not shown in the description; the agent cannot infer return values or success indicators from the description alone.

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%. The description adds no information about the 'container' parameter beyond what the schema shows (a required string). It does not clarify whether the value should be a container name, ID, or partial match, nor does it specify format constraints. The tool's description adds negligible value for parameter understanding.

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 clearly states the action 'Start a Docker container' with a specific verb and resource. The verb 'start' naturally distinguishes this tool from sibling tools like 'docker_stop' (stop), 'docker_restart' (restart), and 'docker_compose_up' (start a compose stack). The purpose is unambiguous and directly actionable.

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?

No guidance is provided on when to use this tool versus alternatives. For example, it does not clarify prerequisites (e.g., container must exist, image must be pulled), nor does it mention when to prefer 'docker_compose_up' for multi-container services. The description lacks any context framing for appropriate usage.

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