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

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the safety bar is lower. The description still adds genuinely non-redundant facts: the sandbox is isolated (mutations don't touch production), it has public internet egress, and the filesystem is ephemeral unless edits are saved. It omits timeout/rate-limit behavior, which keeps it below 5.

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?

Two short, front-loaded sentences with no filler; the isolation and network facts come first. It is efficient, though the brevity borders on under-specification for a nine-parameter destructive tool.

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 destructive command-execution tool with 9 undocumented parameters, no output schema, and no mention of how or where to persist edits, the description leaves an agent without the information needed to call it correctly. It should at minimum name the persistence path and the timeout/wait semantics.

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% across 9 parameters, including nested env, stdin, wait_seconds, timeout_seconds, and idempotency_key, so the description carries the full explanatory burden and provides essentially none of it. 'Public internet' loosely gestures at network-related env, but no parameter is named, constrained, or exemplified.

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?

'Isolated build shell with public internet' identifies a specific execution environment and its network posture, which is enough to tell it apart from file-oriented siblings like files_edit or builds_save. It stops short of a verb+resource statement ('run a command'), relying on the annotation title to supply the verb.

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?

'Save edits afterward' implies the workflow boundary – work done here is ephemeral and must be persisted via another tool – which is real usage guidance. But it never says when to choose this over builds_validate, files_edit, or builds_open, and gives no exclusions for long-running or destructive commands.

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