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

Annotations already flag destructiveHint=true and non-idempotency, so the safety profile is partly covered. The description goes beyond them by explaining the failure mechanism — a cold recovery preserves disk but loses unsaved memory — and by disclosing a billing/capacity gate on admission. Both are behaviors the annotations cannot express, though the jargon ("prepaid runway") is harder to act on than plain language would be.

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?

Three short sentences with little wasted verbiage, but they are ordered backwards: preconditions and caveats come first and the actual action is never delivered at all. The closing sentence's metaphor ("prepaid runway") costs the reader decoding effort without adding precision. Front-loading the operation would make the same length far more useful.

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?

This is a destructive, non-idempotent mutation with no output schema and an undocumented parameter, so the description has to do most of the work. It covers one precondition and one data-loss mode but omits the core semantics: what starting does to an already-running machine, what the response contains, and what the id identifies. An agent would have to call blind on the fundamentals.

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?

The single required parameter `id` has zero schema description coverage, so the description carries the full burden of explaining it — and it says nothing about it. The agent is left to guess whether id is a machine identifier, a snapshot identifier, or something else. This is a clear gap for an otherwise simple one-parameter tool.

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 never states that this tool starts a machine. It opens with a prerequisite ("Read stop_warning/resume_warning before continuing work") and talks about cold recovery and admission requirements, leaving the agent to infer the verb and resource from the name alone. The content is related to the operation but does not define it, so it falls short of even a vague purpose statement.

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?

It gives an explicit precondition — read stop_warning/resume_warning first — and a second precondition that admission needs prepaid runway and physical capacity. That is actionable context for when the call will succeed. What is missing is any routing guidance: nothing distinguishes machine_start from siblings like machine_create, snapshot_start, or exec, and there is no statement of when not to call it.

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