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 by disclosing key behavioral traits: it runs commands via 'sh -c' (enabling shell features), captures both stdout and stderr, and specifies default values for workdir and timeout. However, it doesn't mention potential risks like command injection or authentication needs, leaving some gaps.

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 well-structured and front-loaded with the core purpose, followed by behavioral details and a clear parameter list. Every sentence adds value without redundancy, making it efficient and easy to parse.

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 complexity (SSH command execution with 4 parameters), no annotations, and an output schema (implied by 'Returns' section), the description is complete enough. It covers purpose, behavior, parameters, and return values, providing all necessary context for an agent to use the tool effectively.

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 description coverage is 0%, so the description must compensate, which it does effectively by explaining all four parameters (vm, command, workdir, timeout) with clear semantics, including defaults and purposes (e.g., 'Name of the host', 'Shell command to execute'). This adds significant value beyond the bare 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?

The description clearly states the specific action ('Execute a command on a remote host via SSH') and distinguishes it from sibling tools like vm_file_pull, vm_file_write, etc., which handle file operations rather than command execution. It specifies the verb ('Execute') and resource ('remote host') precisely.

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 usage for SSH command execution but doesn't explicitly state when to use this tool versus alternatives like vm_file_write for file operations or vm_status for status checks. It provides some context (e.g., 'via SSH') but lacks explicit guidance on exclusions or comparisons to siblings.

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 mentions the transfer method (SCP) and that it pulls files, implying a read operation, but does not detail authentication needs, error handling, rate limits, or file overwrite behavior. It adds basic context but lacks depth for a mutation-like tool.

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 well-structured with a clear opening sentence followed by Args and Returns sections. It is front-loaded with the core purpose and efficiently details parameters and return values without unnecessary elaboration, though the Returns section could be slightly more informative.

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 moderate complexity (file transfer via SCP), no annotations, and an output schema present (which covers return values), the description is reasonably complete. It explains the action, parameters, and return intent, but could improve by addressing behavioral aspects like authentication or error scenarios to fully compensate for missing annotations.

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 provides clear semantics for all three parameters (vm as host name, remote_path as absolute path on remote, local_path as destination on local), compensating for the 0% schema description coverage. It explains what each parameter represents, adding value beyond the bare schema, though it doesn't specify format constraints like path syntax.

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 with a specific verb ('Pull'), resource ('a file'), and method ('via SCP'), distinguishing it from siblings like vm_file_push (which pushes files) and vm_file_read (which reads files without transferring). It explicitly mentions source (remote host) and destination (local host), making the action 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 usage by specifying the tool transfers files from remote to local via SCP, but does not explicitly state when to use it versus alternatives like vm_file_read (for reading remote files without local storage) or vm_file_push (for reverse transfers). No exclusions or prerequisites are mentioned, leaving some ambiguity in 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the transfer mechanism (SCP) and return values, but lacks details on permissions required, error handling, file size limits, or network behavior. For a file transfer tool with zero annotation coverage, this is a significant gap in 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 efficiently structured with a clear purpose statement followed by well-organized sections for Args and Returns. Each sentence earns its place by providing essential information without redundancy, making it easy to parse and understand.

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 (file transfer with SCP), no annotations, and an output schema present (which covers return values), the description is reasonably complete. It explains the purpose, parameters, and return expectation, though it could benefit from more behavioral details like authentication requirements or transfer limitations.

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 adds meaningful semantics for all three parameters: 'vm' is explained as a host name from configuration, 'local_path' as a path on the local host, and 'remote_path' as an absolute destination path. With 0% schema description coverage, this fully compensates by providing clear parameter context beyond the bare 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?

The description clearly states the specific action ('Push a file'), the mechanism ('via SCP'), and the resources involved ('from the local host to a remote host'). It distinguishes this tool from sibling tools like 'vm_file_pull' (which would move files in the opposite direction) and 'vm_file_write' (which likely writes content rather than transferring files).

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 usage for file transfer to a remote host, but does not explicitly state when to use this tool versus alternatives like 'vm_file_pull' or 'vm_file_write'. It mentions the 'vm' parameter references a host 'as configured in hosts.toml', which provides some context but no explicit guidance on exclusions or prerequisites.

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 discloses the action (read via SSH) and return behavior (file contents or error), but does not mention authentication requirements, SSH configuration details, error handling specifics, or rate limits. It adds some context but lacks comprehensive behavioral traits.

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 front-loaded with the core purpose, followed by structured sections for Args and Returns. Every sentence earns its place with no wasted words, making it highly efficient and easy to scan.

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 moderate complexity (SSH file read), no annotations, and an output schema (implied by 'Returns'), the description is fairly complete. It covers purpose, parameters, and return values, but could improve by adding more behavioral context like error conditions or prerequisites. The output schema reduces the need to detail return values.

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 compensate. It clearly explains both parameters: 'vm' as the host name configured in hosts.toml and 'path' as the absolute file path on the remote host. This adds essential meaning beyond the bare schema, though it could provide more details like format examples.

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 action ('Read a file') and resource ('from a remote host via SSH'), distinguishing it from siblings like vm_file_write (write) or vm_file_pull (pull/copy). It explicitly mentions the verb 'Read' and the target 'file', making the purpose unambiguous and distinct.

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 usage for reading files via SSH, but does not explicitly state when to use this tool versus alternatives like vm_file_pull (which might copy files) or vm_exec (which might execute commands). It provides basic context but lacks explicit guidance on exclusions or specific scenarios.

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 full burden and does well by disclosing key behavioral traits: it's a write operation (implied mutation), handles content 'safely' via SSH stdin, and mentions error handling in returns. However, it doesn't specify permissions needed, rate limits, or whether files are overwritten, leaving some gaps.

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 front-loaded with the core purpose, followed by a concise explanation of the method, and then structured parameter and return sections. Every sentence earns its place without redundancy, making it efficient and easy to parse.

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 (remote file write via SSH), no annotations, and an output schema present (which covers returns), the description is largely complete. It explains the action, method, and parameters well, but could improve by mentioning side effects (e.g., file overwriting) or SSH-specific requirements.

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 description coverage is 0%, so the description must compensate fully. It does so by clearly explaining all three parameters: 'vm' as the host name from configuration, 'path' as an absolute file path, and 'content' as the data to write. This adds essential meaning beyond the bare 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?

The description clearly states the specific action ('Write content to a file') and resource ('on a remote host via SSH'), distinguishing it from siblings like vm_file_read (read) and vm_file_push/pull (transfer). It explicitly mentions the method ('piping through SSH stdin'), which helps differentiate from other file operations.

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 usage for writing files remotely via SSH, but doesn't explicitly state when to use this vs. alternatives like vm_file_push (which might handle file transfers differently) or vm_exec (which could execute commands). It provides basic context but lacks explicit guidance on exclusions or prerequisites.

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 full burden. It discloses the tool's behavior by stating it returns a formatted list or message if none exist, which is useful. However, it doesn't mention potential limitations like rate limits, authentication needs, or whether the list includes detailed metadata beyond status.

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 extremely concise with two sentences: one stating the purpose and one explaining the return behavior. Every sentence adds value, and it's front-loaded with the core functionality. No wasted words 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 the tool's simplicity (0 parameters, no annotations, but has output schema), the description is mostly complete. It explains what the tool does and the return format. However, it could benefit from slightly more behavioral context (e.g., how the list is formatted or if it's real-time), though the output schema may cover return values.

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 has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose. Baseline is 4 for zero parameters, as it avoids unnecessary information.

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 action ('List all available VMs and containers') and resource ('VMs and containers'), and distinguishes from siblings by focusing on comprehensive listing rather than operations on specific instances. The mention of 'with their status (Incus)' adds technical specificity.

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 usage context by specifying it lists 'all available VMs and containers' with status, suggesting it's for inventory/overview purposes. However, it doesn't explicitly state when to use this vs. alternatives like vm_status (which likely checks a single VM) or provide explicit exclusions.

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 full burden. It mentions 'Restore' implies a destructive write operation, but doesn't disclose critical behaviors: whether the restore is irreversible, if it stops/restarts the VM, permission requirements, or potential data loss. The return statement is vague ('Success confirmation or error message').

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 front-loaded with the core purpose, followed by structured Args and Returns sections. Every sentence earns its place: the first states what it does, the next two explain parameters, and the last covers returns. No 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?

Given a destructive operation with no annotations, 2 parameters (0% schema coverage), and an output schema (implied by 'Returns'), the description is minimally adequate. It covers purpose and parameters but lacks behavioral details (e.g., side effects, auth needs). The output schema existence reduces need to explain return values, but safety concerns are under-addressed.

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 compensate. It clearly explains both parameters: 'vm' as 'Name of the VM or container' and 'snapshot' as 'Name of the snapshot to restore', adding meaningful context beyond the bare schema. However, it doesn't detail format constraints (e.g., naming rules).

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 action ('Restore') and target ('a VM/container to a named snapshot'), specifying the technology context ('Incus'). It distinguishes from siblings like vm_snapshot (create) and vm_list (list), but doesn't explicitly contrast with other restore-related tools if any existed.

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?

No guidance on when to use this tool versus alternatives is provided. While siblings include vm_snapshot (likely for creating snapshots) and others for file operations, the description doesn't mention prerequisites (e.g., snapshot must exist) or when to choose this over other VM management 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the action ('Create a snapshot') but doesn't describe important behavioral traits like whether this operation is reversible, what permissions are required, whether it affects VM availability during snapshot creation, or any rate limits. The return statement is minimal.

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 appropriately sized and well-structured with clear sections for Args and Returns. Each sentence earns its place by providing essential information. It could be slightly more concise by integrating the format guidance more smoothly.

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 (mutating operation with no annotations) and the presence of an output schema, the description is moderately complete. It covers purpose and parameters adequately but lacks behavioral context about the mutation's impact. The output schema existence reduces the need to detail return values, but more operational context would be helpful.

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?

With 0% schema description coverage, the description must compensate for the schema's lack of parameter documentation. It provides meaningful context for both parameters: 'vm' is explained as 'Name of the VM or container' and 'name' gets format guidance ('alphanumeric, hyphens, underscores'). This adds substantial value beyond the bare 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?

The description clearly states the specific action ('Create a snapshot') and resource ('of a VM/container (Incus)'), distinguishing it from siblings like vm_restore (which restores snapshots) or vm_exec (which executes commands). It provides a complete, unambiguous 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?

The description implies usage when snapshot creation is needed, but doesn't explicitly state when to use this tool versus alternatives like vm_restore or other VM management tools. No guidance on prerequisites, timing, or exclusions is provided.

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 discloses that the tool returns status information or an error message, which covers basic behavior, but lacks details on permissions, rate limits, or error conditions. It adds value by specifying the return format, but more behavioral context would improve 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 well-structured and front-loaded with the core purpose, followed by details on returns and parameters. Every sentence adds value without redundancy, and it uses clear sections (Args, Returns) for readability, making it efficient and easy to parse.

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 low complexity (1 parameter) and the presence of an output schema (which handles return values), the description is mostly complete. It covers purpose, parameter semantics, and return overview adequately. However, without annotations, it could benefit from more behavioral details like error handling or prerequisites.

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 compensate. It adds meaning by explaining that the 'vm' parameter is the 'Name of the VM or container', which clarifies beyond the schema's generic string type. However, it doesn't provide examples or constraints (e.g., format, case-sensitivity), leaving some gaps.

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 action ('Get the status') and resource ('a VM/container (Incus)'), distinguishing it from siblings like vm_list (which lists VMs) or vm_exec (which executes commands). It explicitly mentions what information is retrieved, making the purpose unambiguous and distinct.

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 usage when status information (state, IP, resource usage, snapshots) is needed for a specific VM/container, but does not explicitly state when not to use it or name alternatives. For example, it doesn't clarify if vm_list should be used first to find VM names, though this is reasonably inferred from context.

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