start_container

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=true, so safety profile is covered. The description adds value beyond that: the [WRITE] marker, a risk rating, the non-idempotency implication of 'stopped container' scope, and the dry_run preview path. It does not explain behavior when the container is already running. Note the mild tension between the benign 'start' framing and destructiveHint=true, but the description does not assert non-destructiveness, so it is not a contradiction.

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?

Front-loads the operation class and risk marker before the body, and each sentence carries needed information. The Args block is slightly redundant against the surrounding prose (dry_run is mentioned twice) but is not padding since the schema documents nothing.

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 and only 3 parameters, the definition covers what the tool does, when it applies, the inverse operation, and the preview mechanism. It omits edge-case behavior (container already running, permission requirements) and any return-value expectation, keeping it short of fully complete for a mutation tool.

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 carry all parameter meaning, and it does: container_id (id or name), dry_run (preview semantics), and target (config target, optional with a defined default). This is a clear example of the description compensating for an undocumented schema, though it stops short of format examples for container_id.

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?

Specific verb+resource: 'Start a stopped container' clearly distinguishes it from siblings stop_container and restart_container. It also names its inverse ('Inverse: stop it'), so an agent can place it precisely in the lifecycle without opening any schema.

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?

States the condition of applicability ('a stopped container'), signals the write/risk profile, and tells the agent how to preview via dry_run=True. It does not explicitly route the agent to restart_container for an already-running container, so the alternative-selection guidance is implicit rather than spelled out.

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