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

Goes well beyond the annotations: prepaid-credit billing at a per-minute rate, the insufficient_credit error code, idempotent retry semantics via request_key, and critically that 'Stop deletes the VM and files' (destructive consequence not captured by destructiveHint=false). It also states there is no predefined project pipeline, preempting a wrong assumption about siblings like build/push_project.

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 allocation action and cost, then sequences error handling, retry, and polling in roughly the order an agent would need them. It is dense but every clause carries operational information; the 'No predefined project pipeline' fragment is slightly terse and could be folded into a cleaner sentence.

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 stateful, billable allocation tool with a nested limits object and an output schema, the description covers creation, cost, failure recovery, idempotent retry, readiness polling, and teardown consequences. Return-format details are legitimately delegated to the output schema.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: public_key is optional specifically for agents using HTTPS/exec_mac only, and request_key must be reused only after a lost response with identical settings. It does not explain the limits object fields (idle_timeout, max_duration, spend cap), which the schema description covers but the prose does not reinforce.

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?

States a specific verb and resource ('Allocate a full Mac VM') and immediately bounds scope with cost ('billed from prepaid credit at $0.80 an hour by the minute'). This is clearly distinguishable from siblings like stop_mac, get_mac_session, and list_mac_sessions.

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?

Explicitly routes the agent on the error path ('If it returns insufficient_credit, call get_mac_checkout...'), the lost-response path (reuse request_key with identical settings), and the readiness path ('Poll get_mac_session until ready'). It also states when public_key can be omitted ('agents using HTTPS commands only'), which is a genuine when/when-not condition.

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