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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the operation is a non-destructive check, calls it 'cheap and safe', and describes the failure contract involving ok:false with actionable remediation. This is strong transparency beyond what structured data provides.

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 concise and front-loaded, with each sentence serving a distinct purpose: what is checked, when to call it, safety, and failure handling. There is no filler or redundancy.

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 parameterless preflight check with an output schema, the description provides a complete practical contract: prerequisites checked, invocation order, safety profile, and failure behavior. Nothing essential for an agent to select or invoke the tool correctly is missing.

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 tool has zero parameters, so there is no parameter documentation needed. The description appropriately focuses on behavioral contract rather than inputs, matching the baseline expected for a parameterless 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 clearly states the tool's purpose: checking whether the machine can run terrarium. It enumerates the specific checks performed (VirtualBox, state directory, SSH client), making it easy to distinguish from sibling env_* tools that manipulate or inspect environments.

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?

The description gives explicit guidance on when to call this tool ('once before anything else'), notes it is safe to call at any time, and explains how to handle a failure (report the failing check and its fix rather than working around it). This fully covers usage context and expected behavior.

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

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

With no annotations, the description carries the behavioral burden and does substantial work: it explains that clicks go through the hypervisor, require no guest agent, and land exactly where the pixel points. It could add more about potential side effects, but for a click tool the core behavior is clearly disclosed.

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 compact and front-loaded with the action. All three sentences carry useful information, though the middle sentence is slightly long and partially overlaps with schema-provided defaults.

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 click tool with an output schema and 100% parameter coverage, the description covers coordinate sourcing, environment state, button behavior, double-click behavior, and the underlying mechanism. Nothing essential is missing for an agent to call it correctly.

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. The description mostly restates what the schema already says about x/y being pixel positions and the button/double defaults; it adds operational context like "screenshot first" but little new parameter-level meaning.

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 states a specific verb and resource: "Click the environment's screen at a pixel position." It also clarifies the coordinate frame by referencing env_screenshot, which distinguishes this tool from screenshot, scroll, and type operations among the siblings.

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 clear operational conditions: "screenshot first and aim" and "The environment must be running." It also explains button and double-click behavior, but it does not explicitly contrast with alternatives such as env_type or env_scroll.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses boot order (disk first, DVD second), the lack of a golden image and credentials, the fact that env_exec will not work, and the behavior of env_revert resetting the blank disk and restarting the install.

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?

Every sentence serves a purpose: purpose, boot behavior, missing credentials, drive workflow, and post-install promotion. The description is dense but well-structured, front-loading the core use case and then explaining consequences and next steps.

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 complexity and lack of annotations, the description is complete: it explains what is created, the boot/install flow, why env_exec won't work, how to interact during installation, and what to do afterward. An output schema exists, so return-value details are not required here.

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 100%, so the schema already documents all six parameters. The description adds meaningful context beyond the schema by clarifying that iso_path is on the host where the server runs, and by tying disk_gb to the concept of a blank dynamic disk.

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 states a specific action: create a blank environment with an installation ISO in its DVD drive and boot it. It clearly targets OSes with no recipe and no unattended installer, distinguishing this from generic environment creation and from related sibling tools.

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 says when to use this tool: for an OS with no recipe and no unattended installer. It also routes the agent through follow-up tools like env_screenshot, env_type, env_keys, env_click, env_revert, env_promote, and golden_adopt, and warns that env_exec will not work on the result.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It reveals that the operation is clean, non-destructive, preserves disk and list placement, and is reversible via env_start. This is meaningful context beyond the bare tool name, though it could further clarify process termination or edge cases.

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 compact sentences that lead with the action and the key persistence guarantee. Every sentence earns its place, with no filler or redundant schema restatement.

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 single-parameter tool with an output schema, the description gives the essential operational context: what happens (shutdown), what is preserved (disk and list position), and how to reverse it (env_start). It is sufficiently complete for an agent to invoke it correctly without needing more detail.

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?

There is only one parameter, 'name', and the schema already documents it as 'name of the environment' with 100% coverage. The description adds no additional parameter-specific meaning, so the baseline of 3 applies.

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 uses a specific action verb ('Shut') with a clear resource ('an environment') and adds a key differentiator: it keeps the disk and the environment's place in the list. This distinguishes it from destructive siblings like env_rm and aligns it with env_start for lifecycle management.

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?

The description conveys when to use this tool: for a clean, non-destructive shutdown that preserves state. It explicitly references env_start as the way to bring the environment back, which helps an agent choose between down, start, and remove. It does not explicitly mention destructive alternatives, but the context is clear enough.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does so thoroughly: it warns about passwordless sudo and guest-only destruction, timeout kill behavior with child processes, Windows session 0 limitations, and the required SSH credential precondition. This is exemplary transparency.

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 long but every sentence earns its place, covering purpose, shell semantics, command vs script, security, timeout behavior, Windows desktop mode, and prerequisites. The core action is front-loaded, and the length is justified by the tool's complexity and safety implications.

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 6-parameter, side-effect-capable tool with platform-specific behavior and sibling alternatives, the description covers all essential decision points: shell choice, script vs command, timeout behavior, desktop mode, SSH requirement, and fallback tools. It is fully actionable for an agent.

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 already 100%, but the description still adds real meaning: it explains that command is a single shell string interpreted by the guest shell, script reaches stdin and avoids re-parsing, shell overrides the guest's shell, and desktop affects Windows session visibility. These clarifications materially help an agent choose parameter values correctly.

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 opening sentence states the specific verb and resource: run a shell command inside an environment and return exit code and output. It clearly differentiates from screen-interaction siblings like env_screenshot, env_type, and env_click, and from the CLI's terrarium exec.

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?

The description provides explicit guidance on when to use command vs script, when to pass shell, when to set desktop for Windows guests, and states the SSH-credential prerequisite with named alternatives. This goes well beyond implied usage.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses execution time, disk cost, disposability, the precise semantics of env_revert on this environment, and the SSH credential caveat that affects env_exec. This is unusually thorough and directly informs agent expectations.

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?

Four tightly packed sentences, with the core action front-loaded and every subsequent sentence adding operational value. It covers cost, lifetime, revert semantics, and a critical interaction caveat without waste or repetition.

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 creation tool with six parameters and no annotations, the description is impressively complete. It explains the full lifecycle, failure mode, and alternative driving tools, while the presence of an output schema means return-value details need not be duplicated in prose.

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 100%, so the schema already documents all six parameters. The description adds minimal parameter-specific guidance beyond mentioning the golden image's SSH state, which is relevant to the golden parameter. This meets the baseline but does not exceed it.

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 opens with a specific action: 'Create a new environment from a golden image and boot it.' It clearly identifies the resource, the source, and the post-creation behavior, which differentiates env_fork from sibling tools like env_create and env_start.

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 clear context on when to use this tool: when you need an ephemeral environment forked from a golden image and booted. It also provides a specific routing rule for the result: if the golden has no SSH credentials, use env_screenshot, env_type, env_keys, and env_click instead of env_exec. It does not explicitly exclude alternatives like env_create, but the context is strong enough.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains what gets removed, the age-based exclusion for environments without a TTL, and the dry-run safety path. It could mention whether removal is permanent, but the core destructive behavior and conditions are transparent.

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 compact and front-loaded: it states the action and criteria first, then the exception, then the dry-run behavior, then the recommended usage. Every sentence adds necessary information without wasted words.

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 one-parameter tool with an output schema, the description is largely complete. It covers what is removed, when to use it, and how to preview. It does not describe return values in detail, but the presence of an output schema reduces that burden.

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 schema already covers the single dry_run parameter at 100%, including its meaning. The description reinforces it with 'Pass dry_run to see what would go without removing it,' but adds little beyond the schema. Baseline 3 is appropriate.

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 tool removes environments, specifying the exact criteria (TTL expiration or vanished VirtualBox VM). It is scoped and readable, though it does not explicitly contrast itself with the sibling env_rm, so differentiation could be stronger.

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?

The description gives concrete guidance: call it before finishing a session to prevent short-lived environments from piling up. It also explains the dry_run option. It does not explicitly say when not to use it or when to prefer env_rm, but the context is clear enough for most cases.

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

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

With no annotations, the description carries the behavioral burden. It discloses key mechanics: each list entry is one keystroke, chords land as chords, the ctrl run is literal, and the environment must be running. It does not discuss invalid-key handling or focus requirements, but the core side-effect profile is transparent.

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 longer than minimal, but every sentence is functional: purpose, usage boundaries, prerequisite, and valid keys all earn their place. It is slightly dense due to the key-name enumeration, but nothing is wasted.

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 two-parameter tool with an output schema, the description is essentially complete: it provides prerequisites, valid inputs, behavioral semantics, and sibling-tool routing. Minor gaps such as error behavior are not critical for correct invocation.

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 already 100%, but the description adds significant value beyond the schema by enumerating valid key names and clarifying chord semantics. The 'name' parameter is not expanded, but that is already adequately described in the schema.

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?

Description states a specific verb and resource: 'Press keys and chords in the environment.' It immediately scopes itself against env_type ('that env_type cannot express') and distinguishes itself from mouse tools, so an agent can tell what it does and what it is not.

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 says when to use this tool versus env_type, names env_click and env_scroll as the alternatives for mouse actions, and states the prerequisite that the environment must be running. This gives clear decision criteria for tool selection.

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

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

No annotations are provided, so the description carries the full burden. It explicitly states the operation is read-only, which is a key safety trait, and describes exactly what data is returned. Given the zero-parameter, read-only nature, this is sufficient behavioral disclosure.

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 a single well-structured sentence that front-loads the action and resource, includes the key details (SSH ports, running state), and ends with the read-only note. Every word contributes value with no redundancy.

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 zero-parameter, read-only list tool with an output schema, the description is complete. It states what is listed, the specific attributes returned, and the safety profile. No critical information is missing.

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 tool has zero parameters and the schema documents no inputs, so there is nothing for the description to add. The baseline for zero-parameter tools is 4, and the description appropriately focuses on output semantics rather than parameter details.

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 uses a specific verb ('List') and clearly identifies the resources: golden images available to fork from and existing environments, including SSH ports and running status. This distinguishes it from sibling tools like env_create, env_fork, and env_snapshot without needing to open their schemas.

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?

The description clearly communicates what the tool provides, so an agent can infer it should be used when it needs to discover available golden images or environments and their connection/running state. It does not explicitly name alternatives or exclusions, but the read-only listing purpose is unambiguous.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses that this is a full disk copy, takes minutes, consumes a golden's disk space, shuts the environment down, leaves it in place, and creates a durable artifact only the user can remove. This is rich and actionable context.

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?

Four sentences, all substantive, with the core action first followed by cost, side effects, and usage guidance. No filler or redundancy.

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?

The description covers the operation's purpose, resource cost, duration, shutdown behavior, persistence, lifecycle, and cleanup path. Combined with the output schema, an agent has enough context to invoke it correctly and set expectations with the user.

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 100%, so the baseline is 3. The description reinforces the role of each parameter (the environment's current state becomes the image) but adds limited detail beyond the schema's own parameter descriptions.

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 specific operation: flatten an environment's current state into a reusable golden image for env_fork. It distinguishes itself from sibling tools by naming env_fork and env_rm and explaining the golden-image role.

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?

The description explicitly tells the agent when to promote ('only when the user wants the machine kept'), notes the durable result, and points to env_rm for cleanup. It also identifies that the promoted image becomes the source for env_fork, giving clear selection guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals non-obvious behaviors: the connection mirrors env_exec, path conventions differ between guest and host, parent directories are auto-created, and credentials are required. It doesn't mention overwrite behavior, but the output schema covers response semantics.

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 dense sentences with no filler: the core operation is first, followed by path semantics, then directory handling and credentials. Every sentence contributes unique information and nothing repeats the schema.

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 4-parameter tool with full schema coverage and an output schema, the description covers the operation, path conventions, directory recursion, and authentication. The only notable gap is overwrite behavior for existing local files, but the agent still has enough to invoke the tool correctly.

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 100%, so the baseline is 3. The description adds value beyond the schema by clarifying guest vs host path semantics, the Windows forward-slash convention, automatic parent-directory creation, and the role of the recursive flag.

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 states a precise operation: 'Copy a file or directory out of an environment onto this host.' This clearly distinguishes it from siblings like env_push (opposite direction) and env_rm (non-destructive copy), and anchors it to env_exec's connection for context.

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?

Provides concrete usage constraints: guest_path always uses forward slashes even on Windows, local_path is on the host, missing parent directories are created, recursive is needed for directories, and the same credentials as env_exec are required. It doesn't explicitly name alternatives or exclusions, but the guidance is clear and actionable.

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

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

No annotations are provided, so the description carries the responsibility for behavioral disclosure. It does well by stating direction, connection reuse, path format behavior, automatic creation of missing parent directories, recursive behavior, and credential requirements. It leaves overwrite semantics unspecified, which is a minor but real gap for a copy operation.

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 sentences, each with distinct operational content, and the core action is front-loaded. It is efficient overall, though it slightly repeats details already present in the schema parameter descriptions.

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 file-transfer tool with full schema coverage and an output schema present, the description covers the action, direction, path semantics, recursive behavior, parent directory creation, and credentials. Nothing critical for calling the tool correctly appears to be missing.

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 input schema already documents all four parameters at 100% coverage, including host/guest path semantics and recursive meaning. The description mostly restates this per-parameter information rather than adding new parameter-specific value, though it does add tool-level context about the connection and credentials.

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 opening verb phrase 'Copy a file or directory from this host into an environment' clearly identifies the action, resource, and direction. The reference to the same connection env_exec uses also differentiates it from sibling tools such as env_pull or env_exec itself, making the tool's role unambiguous.

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?

The description provides clear contextual guidance: it explains host vs guest paths, forward-slash conventions, the need for recursive when copying directories, and the shared credential requirement with env_exec. It does not explicitly name alternative tools or say when not to use this tool, so it stops short of full exclusion guidance.

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

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

It states the side effect directly: 'Everything done since that snapshot is lost.'

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 concise, with three sentences: action, consequence, and alternative. No unnecessary words.

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?

Within the context of many sibling tools, it clearly distinguishes env_restore from env_revert and references env_snapshot for snapshot creation. The warning about data loss is also provided.

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 description does not elaborate on parameters, but the schema provides descriptions for both 'name' and 'snap' as the environment and snapshot names, respectively. Since schema coverage is 100%, baseline 3 is maintained.

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 purpose: rewinding an environment to a named snapshot. It distinguishes it from env_revert for original state.

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 explicitly says 'Use env_revert instead' for a different scenario, providing a clear alternative. It also warns about losing changes, guiding appropriate usage.

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

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

With no annotations provided, the description fully carries the burden of warning about destructive behavior. It explicitly states that files written in the guest are lost and that the operation discards everything since the fork, while also explaining the performance characteristics (fast because RAM snapshot resumes rather than reboots).

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 compact, with the core action front-loaded in the first sentence. Subsequent sentences add important side effects and performance context without redundancy or 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?

For a one-parameter destructive tool, the description covers what the tool does, what is lost, and why it is fast. An output schema exists, so return-value details are not required. No critical information is missing for an agent to select and invoke the tool correctly.

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 input schema already describes the single parameter as 'name of the environment' with 100% coverage. The description reinforces that the tool operates on an environment but does not add further details about name format, lookups, or edge cases. Baseline 3 is appropriate because the schema handles the parameter documentation.

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 uses a specific verb ('Discard') and clearly identifies the resource and scope: everything done in an environment since it was forked. It also clarifies the outcome ('returning it to its clean snapshot'), which separates it from sibling tools like env_restore that handle arbitrary snapshots.

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?

The description gives clear context for when to use this tool: when you want to reset an environment back to its fork state and lose all changes made inside it. It does not explicitly mention alternatives or exclusions, but the intended use is unambiguous.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that the environment is destroyed, its disks are deleted, everything inside is permanently gone, and the golden image remains unaffected. This is excellent transparency for a destructive operation.

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 deliver the core action first, then the critical irreversibility warning, then the scope clarification about the golden image. Every sentence earns its place, and there is no 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?

For a one-parameter destructive tool with an output schema, the description is complete. It explains the action, the irreversible consequences, and what is not affected, giving an agent all the behavioral context needed to call this tool safely.

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 schema provides 100% coverage for the single required parameter, 'name', described as 'name of the environment'. The description does not add further parameter-level details, but it does not need to because the schema fully documents the only input.

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 tool destroys an environment and deletes its disks, a specific destructive action on a specific resource. It also distinguishes this from siblings like env_down, env_restore, and env_revert by emphasizing permanence and the golden image being untouched.

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?

The description makes the usage context clear: use this when you intend to permanently destroy an environment. It does not explicitly name alternatives such as env_down or env_snapshot for non-destructive operations, but the irreversible wording strongly implies the boundary.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the operation is side-effect-free ('reading a screen changes nothing'), declares the tool needs nothing from the guest ('not even a network'), and reveals the lag behavior that could otherwise confuse an agent interpreting results.

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?

Every sentence earns its place: the first states the primary action, the second gives the key use case, the third clarifies scope and safety, the fourth distinguishes from environment-only input tools, and the last covers the running precondition and lag caveat. The description is front-loaded and free of 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?

For a single-parameter tool with an output schema, the description is complete. It covers purpose, accepted target types, preconditions, safety, and a known timing quirk. There is no missing information an agent would need to decide whether to call this tool and how to interpret its behavior.

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 100%, so the schema already documents the `name` parameter as 'name of the environment, golden image, or VirtualBox VM.' The description adds a little clarity by restating accepted target kinds and emphasizing the tool works on any VirtualBox VM by name, but it does not meaningfully expand parameter semantics beyond what the schema provides.

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 opens with a specific verb-resource pair: 'Capture a running machine's screen and return it as an image.' It also distinguishes this tool from the input-oriented sibling tools by clarifying that env_type, env_keys, env_click, and env_scroll operate only on environments, while env_screenshot can also target golden images and unmanaged VirtualBox VMs.

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?

The description explicitly states when to use the tool: 'This is how to see a guest that has no SSH.' It provides clear preconditions ('The machine must be running'), notes a timing caveat ('The screen lags behind keystrokes'), and gives follow-up guidance to take a fresh screenshot after typing or key presses. It also signals a safe expansion of scope by noting the tool works for machines terrarium does not manage.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that the pointer moves first, then the wheel turns, and explains the sign convention for scrolling direction. It does not mention potential side effects beyond the scroll, but that is acceptable for this focused action.

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 with no filler. It front-loads the core action, then provides the coordinate mechanics, direction semantics, and running-environment prerequisite efficiently.

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?

The description, combined with the fully documented input schema and an output schema, is complete enough for a simple pointer-scroll tool. It covers prerequisites and behavior; only a short explicit note about when to choose this over env_click would make it fully complete.

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 100%, so the input schema already documents all four parameters. The description adds a bit of behavioral context around how x/y and clicks are used, but most parameter semantics already come from the schema, justifying the baseline score.

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 tool scrolls the environment's mouse wheel and explains the coordinate-based behavior. It does not explicitly contrast itself with sibling tools like env_click, but the verb and resource are specific enough to be unambiguous.

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?

The description implies the tool is used when a scroll gesture is needed at a pixel position, and it states a prerequisite: the environment must be running. However, it gives no explicit guidance on when to prefer this over related sibling tools such as env_click or env_type.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that RAM is captured for running environments, that restore resumes rather than reboots, and that the operation is cheap and only stores changed disk blocks. These are genuinely useful behavioral details beyond the bare action.

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 sentences with no filler. The core action is front-loaded, followed by a behavioral nuance (RAM capture) and a cost/performance note. Every sentence earns its place.

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 two-parameter tool with an output schema, the description fully covers purpose, relationship to env_restore, behavioral implications, and cost. There are no significant gaps that would prevent an agent from using it correctly.

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 100% and both parameters (name, snap) are already documented in the schema. The description adds context that the snapshot is named, matching the snap parameter, but does not add new semantic detail beyond what the schema already provides.

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 opens with a clear verb and resource: 'Take a named snapshot of an environment.' It also explicitly distinguishes the tool from its restore counterpart by naming env_restore, so an agent can tell it apart from siblings like env_revert or env_fork.

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?

The phrase 'to come back to later with env_restore' gives clear contextual guidance on how the snapshot relates to future restoration. It implies the intended use but does not explicitly state when not to use it or compare it against other snapshot-like siblings such as env_revert.

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

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

With no annotations, the description carries the behavioral burden. It discloses idempotency ('Does nothing if it is already running'), a blocking wait until SSH answers, and a failure mode for nonexistent names. It does not mention timeout behavior or return values, but the output schema covers some of that.

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, each carrying unique information: main action and wait, idempotent behavior, failure mode with corrective alternative. No filler and the essential behavior is front-loaded.

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 single-parameter boot tool with an output schema, the description covers the core behavior, the no-op case, the error case, and the correct fallback tool. Nothing essential for selecting and invoking it correctly is missing.

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 schema already describes 'name' fully, but the description adds contextual meaning: the name must reference an existing environment, and a missing environment causes failure rather than creation. This helps the agent avoid calling env_start with a new name.

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 opens with a specific verb-resource pair, 'Boot a stopped environment,' and clarifies the exact wait condition ('until SSH answers'). It also distinguishes itself by stating it is a no-op on a running environment and fails for missing names, so it is clearly separate from creation tools like env_fork or env_create.

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 states when to use the tool (start a stopped environment and wait for SSH) and explicitly routes the missing-environment case to env_fork: 'use env_fork to create one.' It does not enumerate all sibling exclusions, but the key alternative is covered.

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

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

With no annotations, the description carries the behavioral burden. It discloses non-obvious traits: keystrokes go wherever focus is, effects appear a moment after return, and the environment must be running. This is meaningful transparency, though it stops short of describing failure modes or how special characters are handled.

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?

Every sentence earns its place: the action, focus caveat, screenshot prerequisite, golden-image routing, running requirement, and delayed effect are all packed concisely with no filler or redundancy.

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 an output schema and full parameter coverage, the description covers the key operational context: preconditions, focus behavior, timing, and environment vs golden-image routing. The main omission is explicit guidance on when env_type is preferable to env_keys, but this is a minor gap.

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 100%, so the schema already documents name, text, and press_enter. The description reinforces the 'as if at a keyboard' framing but adds little per-parameter meaning beyond what the schema provides.

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 identifies a specific action ('Type text into the environment's keyboard') and resource (the environment), and clarifies that keystrokes go to the guest's current focus. It differentiates from click/scroll tools and from golden-image usage by directing to env_fork, but it does not explicitly distinguish from the sibling env_keys, which may overlap in purpose.

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?

The description gives clear usage context: check env_screenshot first, only use on running environments, and for golden images fork first. It also specifies the environment must be running. However, it does not state when to use env_type versus closely related alternatives like env_keys or env_exec, so the guidance is good but not exhaustive.

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

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

With no annotations, the description carries the behavioral transparency burden. It explicitly discloses that the VM is not modified unless take_snapshot is set, that re-running updates the existing record, and that nothing unobserved is recorded ('never invent a user or password'). These are meaningful disclosures beyond schema fields.

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 sentences with no wasted words: the first gives purpose, the second gives side-effect scope, and the third gives an actionable workflow. The dense workflow sentence earns its place because it explains a non-obvious multi-step usage pattern.

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 9-parameter tool with no annotations, the description covers the non-obvious behavioral traits, the credential-adding workflow, and the honesty constraint. Parameter details are already in the schema, and an output schema exists. A minor gap is not explicitly contrasting with golden_import, but 'already exists on this machine' largely covers that.

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 baseline is 3. The description adds value by explaining how user and password are intentionally optional and later populated through a second adoption after observing the guest, and by tying take_snapshot to the only modifying behavior. This goes slightly beyond the schema's per-parameter descriptions.

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 concrete verb ('Record'), a specific resource ('a VirtualBox VM that already exists on this machine'), and the purpose ('as a golden image env_fork can use'). The phrase 'already exists on this machine' clearly distinguishes it from golden_import or other image-creation tools.

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?

Provides a clear workflow: adopt without credentials, fork, observe via env_screenshot, guess via env_type, and re-adopt with working credentials. It also says re-running updates the record. It does not explicitly name golden_import as the alternative, but the 'already exists' qualifier gives enough routing context.

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

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

With zero annotations, the description carries the full burden and delivers: it discloses that the operation is slow and bandwidth-heavy, downloads ~500 MB, boots once for cloud-init, takes minutes (up to an hour for Windows), and fails if the golden already exists. This is exceptional behavioral disclosure covering performance, side effects, process steps, and failure modes.

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 core action is front-loaded in the first sentence, and every subsequent sentence earns its place: performance profile, process steps, the `from` variant, and the failure caveat. It is long (~120 words), but the tool genuinely has two modes and heavy operational consequences, so the density is justified with no wasted phrasing.

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 complex, long-running, resource-heavy build operation with no annotations and an output schema present, the description covers all essential ground: purpose, step-by-step behavior, expected duration, failure condition, and how to source valid inputs. The output schema handles return values, so nothing critical is missing.

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 schema already documents all three parameters, giving a baseline of 3. The description adds genuine value on top: pointing to recipe_list as the source for valid image values and explaining that a `from`-recipe changes the build semantics. cpus and memory_mb receive nothing extra, but they need nothing.

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 — 'Build a golden image from a recipe' — and immediately explains the purpose ('so environments can be forked from it'). The workflow detail (importing, booting for cloud-init, snapshotting) clearly separates it from related siblings like golden_import and golden_adopt, so an agent can distinguish them without opening their schemas.

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?

Gives explicit direction to consult recipe_list for valid image names and warns that rebuilding an existing golden is a human decision, an implicit when-not-to-use. It also distinguishes the two recipe modes (base vs `from`). However, it never explicitly contrasts with golden_import or golden_adopt, which are the closest alternative tools.

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

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

No annotations are provided, so the description carries the full disclosure burden and meets it: it states the side effects ('imported, snapshotted where it stands and recorded as a golden image'), lifecycle ('durable that only the user can remove'), and non-behaviors ('no recipe and no download', 'nothing is seeded', no cloud-init to wait for). This is far richer than what the tool name alone would reveal.

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?

Five sentences, each with a distinct payload: core purpose, sibling contrast, side effects, credential workflow, and durability caution. It is dense and not front-loaded beyond the first sentence, but the length is earned given 5 parameters, multiple related siblings, and significant side effects to disclose.

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?

Output schema exists, so return values need no explanation. The description covers purpose, alternatives, side effects, durability, and the credential-discovery workflow. Minor gaps remain—idempotency on re-import and expected duration for a VM import—but nothing that would block a correct invocation.

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 100%, so the baseline is 3. The description adds genuine value on top by explicitly declaring credentials (key, user, password) optional and prescribing the fallback workflow when they are unknown, which the schema only hints at with 'if it is known'/'if there is one.'

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?

Opens with a specific verb+resource+outcome: 'Register an .ova or .ovf appliance file already on this machine as a golden image.' It explicitly differentiates from the closest sibling ('Unlike golden_get there is no recipe and no download') and cross-references golden_adopt, so an agent can tell this tool apart from related golden-* tools without opening their schemas.

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?

Names golden_get as the alternative and states the differentiator (recipe/download vs. local import). It also prescribes a full decision path: import without credentials, discover login via env_fork/env_screenshot/env_type, record with golden_adopt, and warns 'do it when the task asks for it' for a durable resource. Nothing is left to inference.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it explicitly declares 'Read-only.' It also adds meaningful behavioral context by clarifying that the list reflects buildable images rather than existing environments. It does not mention error/empty-result behavior, but that is a minor gap for a parameterless listing.

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 sentences, each earning its place: core purpose, sibling contrast, and read-only disclosure. The main purpose is front-loaded and there is zero filler or repetition of schema content.

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 parameterless, read-only listing with an output schema available, the description is complete: it states purpose, distinguishes from env_list, and discloses side-effect behavior. Nothing an agent needs to select and invoke it correctly is missing.

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 tool takes zero parameters, so there is nothing for the description to add; the rubric sets a baseline of 4 for parameterless tools. Schema description coverage is trivially 100% with an empty schema.

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 ('List'), a precise resource ('images that CAN be built into golden images with golden_get'), and immediately differentiates itself from env_list by scope. An agent can tell what this tool does and how it differs from siblings 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?

Explicitly names env_list as the alternative and gives the selection condition: recipe_list is the catalogue of what is available to build, while env_list reports what has actually been built and can be forked right now. This contrast leaves no ambiguity about which tool to choose for a given intent.

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