OrbStack MCP Server

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation5/5
Each tool has a clearly distinct purpose with no ambiguity. The tools are organized into logical groups (Docker, Compose, Kubernetes, Linux machines, and core OrbStack operations) with each tool performing a specific, well-defined action on a specific resource. For example, orbstack_docker_stop, orbstack_docker_restart, and orbstack_docker_rm are clearly differentiated in their lifecycle management functions.
Naming Consistency5/5
All tools follow a perfectly consistent naming pattern: 'orbstack_' prefix + resource category (docker/compose/k8s/machine) + action verb (in snake_case). This creates a predictable hierarchy (e.g., orbstack_docker_ps, orbstack_docker_run, orbstack_machine_list, orbstack_machine_start) that makes the tool set immediately understandable and navigable.
Tool Count3/5
With 29 tools, the count feels heavy for a single server, though it covers multiple domains (Docker, Compose, Kubernetes, VM management, and core operations). While each tool appears useful, the high number could overwhelm agents and suggests potential for consolidation (e.g., some Docker operations might be combined with parameters). It's borderline excessive but justified by the broad scope.
Completeness5/5
The tool set provides complete CRUD/lifecycle coverage for all supported domains. For Docker: full container/image management (run, stop, restart, rm, ps, images, inspect, logs, exec, pull). For Linux machines: create, delete, start, stop, list, info, run commands, push/pull files. For Compose/Kubernetes: up/down/ps and start/stop/status respectively. Core OrbStack operations (start/stop/status/version) round out the surface with no apparent gaps.
Average 3.5/5 across 29 of 29 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide significant behavioral information: readOnlyHint=false (mutation), destructiveHint=false (non-destructive), idempotentHint=true (safe to retry). The description adds that it 'stops and removes services,' which clarifies the specific mutation beyond annotations. However, it doesn't mention side effects like removing containers/networks or whether data volumes are preserved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but not optimally structured. The first sentence states the purpose clearly, but the Args/Returns sections are redundant with the schema and output schema. The text could be more front-loaded with critical usage information instead of repeating structured data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 1 parameter but nested schema), annotations cover safety aspects well, and an output schema exists. However, the description lacks important context: it doesn't explain what 'removes' entails (containers, networks, volumes?), doesn't differentiate from sibling tools, and provides minimal parameter guidance despite 0% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 only states '包含项目目录' (contains project directory), which partially explains the 'params' object but doesn't cover the nested 'project_dir' and optional 'service' parameters. The description fails to explain what 'project_dir' means or how 'service' affects the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '使用 Docker Compose 停止并移除服务' (Use Docker Compose to stop and remove services). This is a specific verb+resource combination that distinguishes it from simple stop tools. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_stop' or 'orbstack_compose_up' beyond the Compose context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'orbstack_compose_down' over 'orbstack_docker_stop' or 'orbstack_docker_rm', nor does it specify prerequisites like requiring a running Compose project. The only implied context is Docker Compose projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, but the description adds minimal behavioral context. It mentions '在运行中的 Docker 容器中' (in a running Docker container), which implies a prerequisite, but doesn't disclose execution details like timeout, permissions, interactive vs. non-interactive mode, error handling, or side effects. With annotations covering basic safety, the description adds some value but lacks depth for a command-execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose sentence, followed by 'Args:' and 'Returns:' sections. Each section is brief and to the point, with no redundant information. However, the 'Args:' section could be more integrated into the flow rather than a separate label.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (executing commands in containers), annotations provide basic hints, and an output schema exists (implied by 'Returns: str: 命令输出'), so the description doesn't need to detail return values. However, it lacks context on execution behavior (e.g., security implications, output streaming), prerequisites, and differentiation from siblings. For a command-execution tool, this leaves gaps in guiding the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds a brief note: '包含容器标识和要执行的命令' (contains container identifier and command to execute). This clarifies that 'params' includes 'container' and 'command', matching the schema's properties. However, it doesn't explain parameter formats (e.g., container ID vs. name), command syntax, or examples beyond what's in the schema's property descriptions. The description compensates partially but not fully for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '在运行中的 Docker 容器中执行命令' (execute commands in a running Docker container). It specifies the verb '执行命令' (execute commands) and the resource '运行中的 Docker 容器' (running Docker container). However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_run' (which creates and runs containers) or 'orbstack_machine_run' (which runs commands in machines).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., the container must be running), compare it to sibling tools like 'orbstack_docker_run' (for creating containers) or 'orbstack_machine_run' (for machines), or specify use cases (e.g., debugging, administration). The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond what annotations provide. Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description only states it '获取 Docker 容器的日志输出' (gets Docker container log output), which aligns with annotations but doesn't add meaningful behavioral details like rate limits, authentication needs, or what happens with non-existent containers. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with three sentences, but the structure is somewhat awkward with separate 'Args' and 'Returns' sections that might be better integrated. It's front-loaded with the main purpose, but the additional sections feel redundant since similar information could be inferred from the schema. Every sentence serves a purpose, but the formatting could be more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (Docker logs operation), rich annotations (covering safety and idempotency), and the presence of an output schema (which handles return values), the description is minimally adequate. However, it lacks context about error conditions, performance characteristics, or how it interacts with other Docker tools. For a tool with 0% schema description coverage, it should provide more parameter guidance to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'params: 包含容器标识和日志行数' (params: includes container identifier and log line count), which adds some meaning beyond the schema. However, with 0% schema description coverage, the schema provides no descriptions for the parameters themselves. The description partially compensates by naming two parameters (container and tail) but misses the 'follow' parameter entirely and doesn't explain their semantics in detail, leaving significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as '获取 Docker 容器的日志输出' (get Docker container log output), which is a specific verb+resource combination. It distinguishes itself from siblings like orbstack_docker_inspect or orbstack_docker_ps by focusing specifically on logs. However, it doesn't explicitly differentiate from potential similar logging tools (though none exist in the sibling list), so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While it's clear this is for getting logs, there's no mention of when to choose it over other Docker inspection tools or any prerequisites. The only contextual note is in the schema description for 'follow' parameter, but this isn't part of the main description text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide rich information: readOnlyHint=false (write operation), openWorldHint=true (can pull from any registry), idempotentHint=true (safe to retry), destructiveHint=false (non-destructive). The description adds minimal behavioral context beyond this, only stating it pulls from a '镜像仓库' (image registry). It doesn't contradict annotations, but offers little extra value like rate limits, auth needs, or what happens on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but not optimally structured. The first sentence states the purpose clearly, but the 'Args:' and 'Returns:' sections are redundant since the input and output schemas already document these. This adds unnecessary length without new information. However, it's not verbose, just inefficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a write operation with idempotency), rich annotations, and existing output schema, the description is minimally adequate. It covers the basic purpose but lacks context on error handling, performance, or integration with sibling tools. The annotations and schemas carry most of the load, making the description's gaps less critical but still present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 mentions '包含镜像名称' (contains image name), which aligns with the 'image' parameter in the schema, but provides no additional semantics like format examples (beyond what's in the schema), registry defaults, tag behavior, or authentication requirements. The schema already documents the image parameter well, but the description adds almost nothing beyond restating the parameter exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('拉取' - pull) and resource ('Docker 镜像' - Docker image), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'orbstack_docker_run' or 'orbstack_machine_pull', which might also involve pulling operations. The purpose is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing Docker installed or OrbStack running), when to choose this over 'orbstack_docker_run' (which might implicitly pull), or any constraints. The agent must infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide good coverage: readOnlyHint=false (mutation), destructiveHint=false (non-destructive), idempotentHint=true (safe to retry). The description adds minimal behavioral context beyond this - it mentions '重启结果' (restart result) but doesn't explain what that entails. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (4 lines including Args/Returns sections) but inefficiently structured. The first line is clear, but the Args/Returns sections add minimal value. The structure is front-loaded but could be more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with good annotation coverage and output schema, the description is minimally adequate. It states the action and parameter type, but lacks important context about behavior, error conditions, and relationship to sibling tools. The output schema exists, so return values don't need explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It only states '包含容器 ID 或名称' (contains container ID or name), which repeats what's in the schema properties. It doesn't explain format, validation, or provide examples. With 1 parameter and poor schema documentation, this is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('重启' meaning restart) and the resource ('Docker 容器' meaning Docker container). It distinguishes itself from siblings like 'orbstack_docker_stop' (stop) and 'orbstack_docker_run' (run), but doesn't explicitly contrast with them. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when restart is preferred over stop/start, or how it relates to compose tools. There's no context about prerequisites, dependencies, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic hints (readOnlyHint=false, destructiveHint=false, etc.), but the description adds minimal behavioral context. It mentions '传输结果' (transfer result) as the return, but doesn't describe what happens on failure, whether files are overwritten, authentication requirements, or network behavior. With annotations covering only basic safety, the description should provide more operational context for a file transfer tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but could be better structured. The first sentence states the purpose clearly, but the Args/Returns sections are redundant with the schema and output schema. The information could be more front-loaded and eliminate the schema-like formatting to be more conversational for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 between systems), annotations provide basic safety hints, and an output schema exists (so return values are documented elsewhere), the description is minimally complete. However, it lacks important context about error conditions, file overwrite behavior, and machine connectivity requirements that would be helpful for an agent using this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions parameters ('包含源文件路径、可选的目标路径和机器名') but provides no additional semantics beyond what's already in the schema. Since schema description coverage is 0%, the schema itself lacks parameter descriptions, making the description's brief mention insufficient. However, the parameter structure is simple (one object with three fields), so baseline 3 is appropriate given the low complexity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '从 Linux 机器拉取文件到 macOS' (pull files from Linux machine to macOS). This is a specific verb+resource combination that distinguishes it from sibling tools like 'orbstack_machine_push' (which goes in the opposite direction) and 'orbstack_machine_run' (which executes commands). However, it doesn't explicitly differentiate from all siblings, just implies directionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While the title '从 Linux 机器拉取文件' suggests it's for pulling files from Linux machines, there's no mention of prerequisites, when not to use it, or explicit comparison with similar tools like 'orbstack_machine_push' for the reverse operation or 'orbstack_docker_pull' for Docker images.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond annotations. Annotations already indicate this is not read-only, not open-world, not idempotent, and not destructive. The description adds that it transfers files between macOS and Linux machines, but doesn't provide additional behavioral details like whether it overwrites existing files, what permissions are required, or how it handles errors. With annotations covering the basic safety profile, this earns a baseline score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise with three sentences, but the structure could be improved. The first sentence clearly states the purpose, but the Args and Returns sections are overly brief and don't add meaningful information beyond what's obvious from the tool name. The description is front-loaded with the main purpose, but subsequent sentences don't earn their place with valuable additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a file transfer tool with 1 parameter (a nested object with 3 fields), 0% schema description coverage, and an output schema exists, the description is minimally adequate. It states what the tool does but lacks important context about how it works, what errors might occur, or what the '传输结果' (transfer result) output actually contains. The existence of an output schema helps, but the description should provide more operational context for a tool that modifies system state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden for parameter documentation. While the description mentions '包含源文件路径、可选的目标路径和机器名' (contains source file path, optional destination path, and machine name), this only lists parameter names without explaining their semantics, constraints, or relationships. It doesn't clarify what format paths should use, what 'machine name' refers to, or how defaults work when optional parameters are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '将文件从 macOS 推送到 Linux 机器' (push files from macOS to Linux machine). It specifies both the verb ('push') and resource ('files'), and distinguishes it from sibling tools like 'orbstack_machine_pull' which would move files in the opposite direction. However, it doesn't explicitly differentiate from other file-related tools like 'orbstack_docker_exec' or 'orbstack_machine_run' that might also handle files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate compared to other file transfer methods or sibling tools like 'orbstack_machine_pull' for reverse transfers. The only implicit usage context is transferring files from macOS to Linux, but no explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key behavioral hints: readOnlyHint=false (mutation), idempotentHint=true (safe to retry), destructiveHint=false (non-destructive). The description adds that it returns a string result, which is useful context not in annotations. However, it doesn't disclose rate limits, authentication needs, error conditions, or what '启动结果' specifically entails (e.g., success message, error). With annotations covering safety and idempotency, the description adds some value but lacks rich behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with a clear main sentence, but the Args/Returns sections are redundant with the schema and output schema. The sentence '启动指定的 Linux 机器。' is front-loaded and efficient, but the structured parts add verbosity without new information, reducing overall conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 parameter, annotations with safety hints, and an output schema, the description is minimally adequate. It states the action and return type, but lacks details on error handling, prerequisites (e.g., machine must exist), or side effects. For a mutation tool, more context on behavior and usage would improve completeness, though annotations help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description only states '包含机器名称' (contains machine name), which partially explains the 'params' object but doesn't clarify the nested 'name' parameter's purpose, format, or constraints (e.g., max length 100). It adds minimal meaning beyond the bare schema, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('启动' meaning 'start') and the resource ('指定的 Linux 机器' meaning 'specified Linux machine'). It distinguishes from siblings like orbstack_machine_stop, orbstack_machine_list, and orbstack_machine_info by specifying the start operation. However, it doesn't explicitly differentiate from orbstack_start (which appears to be a general start command) or orbstack_machine_run (which might execute commands).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., machine must exist, be stopped), exclusions (e.g., don't use if already running), or comparisons to siblings like orbstack_machine_stop, orbstack_machine_run, or orbstack_start. The agent must infer usage from the name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key behavioral hints: readOnlyHint=false (write operation), idempotentHint=true (safe to retry), destructiveHint=false (non-destructive). The description adds context by specifying it's for Linux machines, which helps clarify scope beyond annotations. No contradictions with annotations are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but structured with Args and Returns sections. However, the content is sparse—the Args section merely repeats the parameter name without elaboration, and the Returns section is vague ('停止结果' meaning 'stop result'). It could be more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a write operation with idempotency) and low schema coverage, the description is incomplete. It lacks details on error conditions, side effects, or what the output schema provides. The presence of an output schema mitigates some gaps, but overall context is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It only mentions '包含机器名称' ('contains machine name'), which is minimal and doesn't explain format, constraints, or examples. With one undocumented parameter, this is inadequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('停止' meaning 'stop') and the resource ('指定的 Linux 机器' meaning 'specified Linux machine'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_machine_delete' or 'orbstack_docker_stop', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., the machine must be running), exclusions (e.g., cannot stop if in use), or compare to similar tools like 'orbstack_machine_delete' for removal or 'orbstack_stop' for broader system shutdown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds that it returns 'JSON 格式的完整容器信息，包括网络、挂载、环境变量等' (complete container information in JSON format, including network, mounts, environment variables, etc.), which gives useful context about output content. However, it doesn't mention rate limits, authentication needs, or other behavioral traits beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it starts with the purpose, then specifies the return format and content, and lists Args and Returns sections. Each sentence adds value without redundancy. It could be slightly more front-loaded by integrating parameter info earlier, but it's efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, read-only, idempotent), annotations cover safety aspects, and an output schema exists (implied by 'Has output schema: true'), the description is reasonably complete. It explains what the tool does, the parameter, and the return format. For a simple inspection tool, this provides adequate context, though usage guidelines are lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries more burden. It states 'params: 包含容器 ID 或名称' (params: contains container ID or name), which clarifies the single parameter's purpose. However, it doesn't provide examples, format details, or constraints beyond what's implied. With 0% schema coverage and 1 parameter, this adds basic semantics but lacks depth, aligning with the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '查看 Docker 容器的详细配置和状态信息' (View detailed configuration and status information of Docker containers). It specifies the verb ('查看' - view/inspect) and resource ('Docker 容器' - Docker containers). However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_ps' (which lists containers) or 'orbstack_machine_info' (which inspects machines), so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'orbstack_docker_ps' for listing containers or 'orbstack_docker_logs' for logs, nor does it specify prerequisites or contexts for use. The only implicit guidance is that it's for inspecting container details, but this is covered by purpose clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), openWorldHint=true (flexible inputs), idempotentHint=false (non-idempotent), and destructiveHint=false (non-destructive). The description adds that it '支持端口映射、卷挂载、环境变量等配置' (supports port mapping, volume mounting, environment variables, etc.), which provides useful context about configurability beyond annotations. However, it doesn't mention potential side effects like resource consumption, network exposure, or that it might fail if the image doesn't exist locally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, support features, Args, Returns). It's front-loaded with the main purpose, and each sentence adds value. However, the 'Args' section is redundant with the schema and could be more concise by integrating with the feature list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (creating/running containers with multiple config options), annotations cover safety aspects, and the output schema exists (implied by 'Returns: str'), so the description doesn't need to detail return values. However, it lacks guidance on usage context, error conditions, or dependencies (e.g., Docker daemon running), making it minimally adequate but with gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description has an 'Args:' section listing 'params: 容器运行参数' (container run parameters). This adds minimal semantic value beyond the schema's detailed property descriptions (image, ports, volumes, etc.). The description doesn't explain parameter interactions or provide examples of the 'params' object structure, leaving the schema to carry most of the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '创建并运行一个新的 Docker 容器' (create and run a new Docker container), which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_pull' (which pulls images) or 'orbstack_docker_restart' (which restarts existing containers), though the 'new' aspect implies creation rather than management of existing containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an image pulled first), when to use 'orbstack_docker_exec' for running commands in existing containers, or when 'orbstack_compose_up' might be better for multi-container setups. The lack of context leaves the agent guessing about appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds context by specifying it returns details like distribution, architecture, status, and IP addresses, which helps the agent understand the return format. However, it doesn't disclose behavioral traits beyond this, such as rate limits or authentication needs, leaving some gaps despite the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the main purpose followed by examples and parameter/return info. It uses three clear sections (purpose, Args, Returns) with minimal waste. However, the inclusion of 'Args:' and 'Returns:' labels adds slight redundancy, as this info is partly covered elsewhere, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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), rich annotations (readOnly, idempotent, etc.), and the presence of an output schema (implied by 'Returns: str'), the description is mostly complete. It explains what the tool does and what information it returns, though it could benefit from more usage guidance relative to siblings. The annotations and schema handle safety and structure well, so the description adds sufficient value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by stating '包含机器名称' (contains machine name) and listing the parameter in the Args section. This adds meaning beyond the schema, which only defines the parameter structure without explaining its purpose. However, it doesn't provide detailed semantics like format constraints or examples, so it's adequate but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '获取指定 Linux 机器的详细信息' (Get detailed information about a specified Linux machine). It specifies the verb ('获取' - get) and resource ('Linux 机器' - Linux machine), and lists examples of information included. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_machine_list' or 'orbstack_status', which is why it doesn't earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'orbstack_machine_list' (which lists machines) or 'orbstack_status' (which might provide status information), nor does it specify prerequisites or exclusions. The only implied usage is when you need details for a specific machine, but this is minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key behavioral hints: readOnlyHint=false (implies mutation), idempotentHint=true (safe to retry), destructiveHint=false (non-destructive). The description adds minimal context by specifying it stops the Kubernetes cluster, but doesn't elaborate on effects (e.g., what happens to running pods) or operational details. With annotations covering core traits, the description adds some value but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but includes an extra 'Returns:' section that merely repeats what the output schema would cover ('str: 停止结果'), adding redundancy. The core purpose is stated in one clear sentence, but the return statement is wasteful given the presence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, annotations cover key behaviors, output schema exists), the description is reasonably complete. It states what the tool does, and with annotations and output schema, the agent has sufficient context. However, it could benefit from more operational guidance (e.g., idempotency note) to reach a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100% (though trivial). The description doesn't need to explain parameters, so it appropriately focuses on the action. A baseline of 4 is justified as the description handles the parameter-less case adequately without unnecessary detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('停止' meaning 'stop') and target resource ('OrbStack 的 Kubernetes 集群' meaning 'OrbStack's Kubernetes cluster'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_k8s_start' or 'orbstack_stop' beyond the Kubernetes focus, which is why it doesn't reach a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., cluster must be running), when-not-to-use scenarios, or comparisons to related tools like 'orbstack_k8s_start' or general 'orbstack_stop'. The agent must infer usage from the name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds minimal context by specifying the output format ('格式化表格' - formatted table), which is useful but doesn't detail aspects like sorting, filtering, or error handling. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, stating the core purpose in the first sentence. The second sentence about the return value adds necessary clarity without redundancy. However, it could be slightly more structured by explicitly separating purpose and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, read-only), annotations cover safety aspects, and an output schema exists (implied by 'Has output schema: true'), the description is reasonably complete. It specifies the output format, which complements the structured data, though more behavioral details like performance or limitations could enhance it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema description coverage, the baseline is high. The description doesn't need to explain parameters, and it appropriately focuses on the action and output. No additional parameter semantics are required or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '列出' (list) and resource '本地所有 Docker 镜像' (all local Docker images), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_ps' (which lists containers) or 'orbstack_machine_list' (which lists machines), missing full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like checking for available images before running containers or comparing with 'orbstack_docker_pull' for fetching new images, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations: it clarifies that this tool checks '运行状态' (running status) for services in a Docker Compose project, which isn't covered by annotations like readOnlyHint or idempotentHint. Annotations already indicate it's safe (readOnlyHint: true, destructiveHint: false), but the description usefully specifies the scope (Compose services). No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence. The Args and Returns sections are structured but could be more integrated. It's concise with minimal waste, though the separation into sections might slightly reduce readability for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (checking Compose service status), annotations cover safety (readOnlyHint, etc.), and an output schema exists (indicating returns a string), the description is reasonably complete. It specifies the tool's scope and parameters, though it lacks usage guidance relative to siblings. For a read-only tool with good annotations, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates partially by noting '包含项目目录' (includes project directory) in the Args section. However, it doesn't explain the nested 'service' parameter or provide examples. The input schema fully documents parameters (project_dir, service), so the baseline of 3 is appropriate as the schema does the heavy lifting despite low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '查看 Docker Compose 项目中各服务的运行状态' (View the running status of services in a Docker Compose project). It specifies the verb ('查看' - view) and resource ('Docker Compose 项目中各服务的运行状态' - running status of services in a Docker Compose project). However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_ps' or 'orbstack_status', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'orbstack_docker_ps' (for general Docker containers) or 'orbstack_status' (for overall Orbstack status), nor does it specify prerequisites or exclusions. The agent must infer usage from the tool name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key behavioral hints: readOnlyHint=false (mutation), idempotentHint=true (safe to retry), destructiveHint=false (non-destructive). The description adds that it stops '运行中的' (running) containers, clarifying scope, but doesn't mention side effects (e.g., container state changes, potential data loss) or error conditions beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
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. It avoids redundancy but could be more concise by integrating parameter details into a single sentence rather than separate sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with annotations covering safety (idempotent, non-destructive) and an output schema (returns str), the description is reasonably complete. It specifies the target (running containers) and parameter semantics, though it lacks error handling or performance details that could aid the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section specifies that 'params' contains '容器 ID 或名称' (container ID or name), matching the schema's 'container' property. However, it doesn't explain format constraints (e.g., length, uniqueness) or provide examples, offering minimal added value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('停止运行中的' - stop running) and resource ('Docker 容器' - Docker containers). It distinguishes from siblings like orbstack_docker_restart (which restarts) and orbstack_docker_rm (which removes), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., container must be running), exclusions, or comparisons with similar tools like orbstack_docker_restart or orbstack_stop, leaving the agent without contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond annotations by stating '这将停止所有运行中的容器和 Linux 机器' (This will stop all running containers and Linux machines), which clarifies the scope and impact of the operation. Annotations already indicate it's not read-only (readOnlyHint: false), idempotent (idempotentHint: true), and non-destructive (destructiveHint: false), so the description doesn't contradict these but provides additional behavioral detail about what gets affected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: the first sentence states the core purpose, the second adds crucial behavioral context, and the third specifies the return type. Every sentence earns its place with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 0 parameters, annotations cover safety aspects (idempotent, non-destructive), and there's an output schema (implied by 'Returns: str'), the description is reasonably complete. It explains what the tool does and its scope, though it could benefit from more usage guidance relative to siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter documentation in the description. The baseline for 0 parameters is 4, as the description appropriately doesn't discuss parameters that don't exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('停止' meaning 'stop') and the target ('OrbStack 服务' meaning 'OrbStack service'), which is a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from sibling tools like 'orbstack_docker_stop' or 'orbstack_machine_stop', which appear to stop specific components rather than the entire service.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate (e.g., for stopping the entire OrbStack environment) versus using more specific stop tools for containers or machines, nor does it discuss prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide substantial information (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), covering safety and idempotency. The description adds that it runs 'docker compose up -d' (detached mode) and mentions the project directory requirement, which provides useful operational context. However, it doesn't disclose potential side effects like container recreation or network creation that 'docker compose up' might entail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, execution details, Args, Returns). It's concise at 4 sentences with no wasted words. The information is front-loaded with the core purpose first. The bilingual presentation (Chinese purpose, English labels) is slightly inconsistent but doesn't hinder understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (starting Docker Compose services), the description covers the essential what, how, and parameters. Annotations provide safety/behavioral context, and the output schema exists (though not shown), so return values needn't be detailed. The main gap is lack of explicit differentiation from sibling Docker tools, but overall it's reasonably complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It explains that 'params' contains '项目目录和可选的服务名' (project directory and optional service name), which correctly identifies the two parameters. It adds that the service parameter is optional and when unspecified operates on all services. This provides meaningful semantic context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '使用 Docker Compose 启动服务' (use Docker Compose to start services). It specifies the exact command executed ('docker compose up -d') and distinguishes it from other compose operations like 'down' or 'ps'. However, it doesn't explicitly differentiate from other Docker-related tools in the sibling list beyond the compose context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning '在指定目录中' (in the specified directory) and referencing the 'docker-compose.yml' file, but doesn't provide explicit guidance on when to use this tool versus alternatives like 'orbstack_docker_run' or 'orbstack_machine_start'. It mentions the service parameter is optional but doesn't explain trade-offs or scenarios for specifying services.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds useful context about the default filtering behavior (running containers only) and output format (formatted table), which goes beyond what annotations provide. However, it doesn't mention rate limits, authentication needs, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three clear sections: purpose statement, parameter explanation, and return value description. Each sentence earns its place. However, the Args/Returns formatting could be more integrated with the natural language description rather than separate labeled sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple read-only listing tool with good annotations and an output schema (which handles return value documentation), the description provides sufficient context. It covers the tool's purpose, parameter behavior, and output format. For a tool with only one parameter and clear safety annotations, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (the schema has no parameter descriptions), the description carries the full burden. It clearly explains the 'all' parameter's purpose and default value, which covers the single parameter's semantics effectively. The description compensates well for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as '列出 Docker 容器' (list Docker containers), which is a specific verb+resource combination. It distinguishes from siblings like 'orbstack_docker_images' (lists images) and 'orbstack_docker_inspect' (shows detailed container info). However, it doesn't explicitly differentiate from 'orbstack_compose_ps' which also lists containers but specifically for Docker Compose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by mentioning the default behavior (shows only running containers) and how to change it (set all=True). However, it doesn't explicitly state when to use this tool versus alternatives like 'orbstack_docker_inspect' for detailed container information or 'orbstack_compose_ps' for Compose-managed containers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide rich behavioral information: readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds minimal value beyond this, only stating it returns a string status. It doesn't contradict annotations (the description aligns with read-only behavior), but provides little additional context about what the status string contains, format, or interpretation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose in the first sentence. The second sentence about return type is somewhat redundant given the output schema exists, but it's not excessive. Overall efficient with minimal waste, though the return statement could potentially be omitted since output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, rich annotations, output schema exists), the description is reasonably complete. It states what the tool does, and the annotations cover safety and behavioral aspects. The output schema handles return value documentation. The main gap is lack of guidance on when to use versus sibling tools, but for such a simple diagnostic tool, the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100% (though trivial since there are no parameters). With no parameters to document, the description appropriately doesn't discuss parameters. A baseline of 4 is appropriate for zero-parameter tools where the schema fully covers the empty parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '查看 OrbStack Kubernetes 集群的状态' (view OrbStack Kubernetes cluster status). It specifies both the verb (view/check) and the resource (Kubernetes cluster status), and distinguishes it from sibling tools like orbstack_k8s_start and orbstack_k8s_stop. However, it doesn't explicitly differentiate from the general orbstack_status tool, which might check overall OrbStack status rather than specifically Kubernetes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (checking Kubernetes cluster status) but provides no explicit guidance on when to use this tool versus alternatives like orbstack_status or orbstack_k8s_start/stop. There's no mention of prerequisites, typical use cases, or when not to use it. The context is clear but lacks sibling differentiation guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), destructiveHint=false (non-destructive), idempotentHint=false (non-idempotent), and openWorldHint=false (closed-world). The description adds useful behavioral context beyond annotations: it specifies supported distributions, mentions Apple Silicon compatibility with amd64 architecture, and indicates that name is optional (auto-generated if not specified). However, it doesn't describe important behavioral aspects like whether this creates persistent VMs, what resources are allocated, or potential rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, feature highlights, and separate Args/Returns sections. It's appropriately sized at 4 sentences (Chinese). However, the 'Returns: str: 创建结果' section is redundant since there's an output schema, and the structure could be more front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool (readOnlyHint=false) with 1 parameter (nested object with 3 sub-parameters), 0% schema description coverage, but with an output schema present, the description provides adequate context. It covers the core purpose, supported distributions, architecture considerations, and parameter overview. The output schema means return values don't need explanation in the description. However, for a VM creation tool, more details about resource allocation or creation constraints would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden for parameter documentation. The description provides good semantic information: it lists supported distributions, explains the arch parameter's purpose for Apple Silicon, and mentions that params includes '发行版名称、可选的机器名和架构' (distribution name, optional machine name, and architecture). However, it doesn't fully document all parameter details like format constraints or default behaviors beyond what's implied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '创建一个新的 Linux 虚拟机' (creates a new Linux virtual machine). It specifies the verb ('创建' - create) and resource ('Linux 虚拟机' - Linux virtual machine), and distinguishes from siblings like orbstack_machine_delete, orbstack_machine_info, and orbstack_machine_list. However, it doesn't explicitly differentiate from other creation tools like orbstack_docker_run or orbstack_compose_up, which also create resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some implied usage context by listing supported distributions (ubuntu, debian, fedora, arch, alpine) and mentioning the arch parameter for Apple Silicon. However, it doesn't explicitly state when to use this tool versus alternatives like orbstack_docker_run (for containers) or orbstack_compose_up (for Docker Compose). No explicit 'when-not-to-use' guidance or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, which already tells the agent this is a non-destructive, non-idempotent operation with specific parameters. The description adds that it executes commands and returns output, which is consistent with annotations. It doesn't provide additional behavioral context like execution time limits, error handling, or authentication requirements beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: it starts with the core purpose, then explains parameter usage, and ends with return value. Each sentence adds value without redundancy. However, the Chinese formatting with line breaks slightly affects readability, and it could be more front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (command execution with optional targeting), the description covers the essential aspects: what it does, parameter semantics, and return type. With annotations providing safety hints and an output schema indicating a string return, the description doesn't need to explain return values in detail. It adequately complements the structured data for this type of tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The description compensates by explaining the 'params' object contains the command, optional machine name, and user, and clarifies default behavior when machine isn't specified. It adds meaningful context beyond the bare schema, though it could provide more detail on parameter formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '在 Linux 机器中执行命令并返回输出' (execute commands in Linux machines and return output). It specifies the verb ('执行命令' - execute commands) and resource ('Linux 机器' - Linux machines). However, it doesn't explicitly differentiate from sibling tools like 'orbstack_docker_exec' or 'orbstack_machine_info', which reduces it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: '可以指定目标机器和执行用户。不指定机器时使用默认机器' (can specify target machine and execution user; uses default machine if not specified). This gives basic guidance on when to use optional parameters. However, it doesn't explain when to choose this tool over alternatives like 'orbstack_docker_exec' or other execution tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds context by specifying what information is returned ('是否正在运行、版本等基本状态' - whether it's running, version, etc.), which helps the agent understand the output format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose in the first sentence, followed by details on return values. It's concise with two sentences in Chinese and one in English, but the English 'Returns: str: OrbStack 状态信息' is redundant with the Chinese text, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, annotations cover safety, output schema exists), the description is mostly complete. It explains what information is returned, and the output schema handles return values. However, it lacks usage context compared to siblings, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%. The description doesn't need to explain parameters, so it meets the baseline. It implicitly confirms no inputs are required by not mentioning any, which is appropriate for this parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '获取 OrbStack 的运行状态信息' (Get OrbStack's running status information). It specifies the verb '获取' (get) and resource 'OrbStack 运行状态信息' (OrbStack running status information), distinguishing it from sibling tools like orbstack_start or orbstack_stop. However, it doesn't explicitly differentiate from orbstack_k8s_status, which might cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like orbstack_k8s_status for Kubernetes status or orbstack_version for version info, nor does it specify prerequisites or exclusions. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying the return type ('str: OrbStack 版本信息'), which clarifies the output format beyond annotations. No contradictions with annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: one sentence for the purpose and one for the return value. Every sentence adds essential information without redundancy, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, annotations cover safety, output schema exists), the description is largely complete. It states the purpose and return type. However, it lacks context on when to use this versus similar tools like 'orbstack_status', which slightly reduces completeness for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%. With no parameters to document, the description doesn't need to compensate. It appropriately focuses on the tool's purpose and return value, earning a high baseline score for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '获取 OrbStack 版本号' (Get OrbStack version number). It uses a specific verb ('获取') and resource ('OrbStack 版本号'), making the intent unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'orbstack_status' which might also provide version information, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'orbstack_status' that might overlap in functionality, nor does it specify prerequisites or appropriate contexts for version checking. This leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations. While annotations already indicate destructiveHint=true (mutation) and readOnlyHint=false, the description clarifies the prerequisite condition (container must be stopped) and the force deletion workflow. This provides important operational guidance not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with clear sections (purpose, prerequisites, Args, Returns). Each sentence earns its place by providing essential information. The structure is front-loaded with the core purpose first, followed by important constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a destructive operation with 1 parameter and an output schema exists, the description provides good context about prerequisites and behavior. The output schema handles return value documentation, so the description appropriately focuses on operational guidance. It covers the essential aspects for a deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the schema provides no parameter documentation. The description adds some value by mentioning '容器 ID 或名称' (container ID or name) in the Args section, but doesn't provide format examples, constraints, or clarify what 'params' contains beyond referencing the container identifier. It partially compensates for the schema gap but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('删除' meaning delete) and resource ('Docker 容器' meaning Docker container). It distinguishes from siblings like 'orbstack_docker_stop' (which stops containers) and 'orbstack_docker_ps' (which lists containers) by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context about when to use it ('容器必须已停止才能删除' - container must be stopped before deletion) and mentions an alternative approach ('如需强制删除运行中的容器请先停止' - if you need to force delete a running container, stop it first). However, it doesn't explicitly name specific sibling tools as alternatives for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it specifies idempotency ('无副作用' meaning 'no side effects' when already running), which aligns with the idempotentHint=true annotation, and clarifies the return type ('str: 启动结果' meaning 'str: start result'). Annotations cover readOnlyHint=false, destructiveHint=false, etc., but the description enhances this with practical usage notes, earning a high score without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: the first sentence states the purpose, the second adds crucial behavioral context, and the third specifies the return value. Every sentence earns its place with no wasted words, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, idempotent operation), the description is complete. It explains what the tool does, when to use it, behavioral traits, and the return type. With an output schema present, it doesn't need to detail return values further, and annotations provide additional safety context, making this fully adequate for the agent's needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description doesn't need to add parameter details, and it correctly doesn't mention any. Since there are no parameters, the baseline is 4, as it appropriately avoids unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('启动' meaning 'start') and the target resource ('OrbStack 服务' meaning 'OrbStack service'), providing a specific verb+resource combination. It distinguishes from siblings like 'orbstack_stop' by indicating it starts rather than stops the service. However, it doesn't explicitly differentiate from other start-related tools like 'orbstack_k8s_start' or 'orbstack_machine_start', which limits the score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage with the statement '如果 OrbStack 已在运行，此操作无副作用' (meaning 'if OrbStack is already running, this operation has no side effects'), which implies it's safe to call regardless of current state. However, it doesn't explicitly mention when to use this tool versus alternatives like 'orbstack_status' to check status first, or provide exclusions, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond what annotations provide. While annotations already indicate destructiveHint=true, the description explicitly warns that the operation is irreversible ('不可撤销') and that all data will be permanently deleted ('机器中的所有数据将被永久删除'). This provides crucial safety information that enhances the agent's understanding of the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and front-loaded: it starts with the core purpose, immediately follows with a critical warning, then provides clear Arg/Return sections. Every sentence earns its place - the warning is essential for a destructive operation, and the parameter/return documentation addresses basic usage needs without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with good annotations and an output schema, the description is mostly complete. It covers the irreversible nature and data loss, which are critical for safe use. The main gap is the lack of explicit guidance on when to use this versus alternatives (like stopping vs deleting), but the warning provides sufficient context for an agent to exercise caution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (the schema has no descriptions for the top-level 'params' property), the description compensates by explaining that 'params' should contain the machine name ('包含机器名称'). However, it doesn't specify the exact parameter structure (that 'params' is an object with a 'name' field) or provide format details like the 1-100 character length constraint mentioned in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('删除' meaning delete) and resource ('指定的 Linux 机器' meaning specified Linux machine). It distinguishes itself from sibling tools like orbstack_machine_info, orbstack_machine_list, orbstack_machine_start, and orbstack_machine_stop by specifying a destructive deletion operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit guidance through the warning about irreversible deletion, suggesting it should be used cautiously. However, it doesn't explicitly state when to use this tool versus alternatives like orbstack_machine_stop (for temporary shutdown) or orbstack_machine_remove (if such existed), nor does it mention prerequisites like needing the machine to be stopped first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide key hints (idempotentHint=true, destructiveHint=false, readOnlyHint=false), but the description adds valuable context: it specifies the cluster is lightweight and single-node, which helps set expectations. No contradiction with annotations exists, and it complements them by describing the cluster type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, followed by additional context about the cluster and return value. Each sentence adds value: the first states the purpose, the second provides cluster details, and the third specifies the return type. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0 parameters, rich annotations (idempotent, non-destructive), and an output schema (implied by 'Returns: str'), the description is complete. It covers purpose, cluster characteristics, and return type, leaving no gaps for an AI agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately focuses on the tool's purpose and behavior without redundant parameter details, earning a baseline score of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('启动' meaning 'start') and resource ('OrbStack 内置的 Kubernetes 集群' meaning 'OrbStack's built-in Kubernetes cluster'), distinguishing it from sibling tools like orbstack_k8s_stop and orbstack_k8s_status. It also mentions the cluster is lightweight and single-node, adding useful context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to start the Kubernetes cluster, with clear context from sibling tools (e.g., use orbstack_k8s_stop to stop it, orbstack_k8s_status to check status). However, it lacks explicit when-not-to-use guidance or prerequisites, such as whether OrbStack must be running first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying what information is displayed (machine name, distribution, architecture, running status) and that it returns a string with the list, which complements the annotations without contradiction. It doesn't mention rate limits or auth needs, but those aren't critical here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by specifics on displayed information and return type. Every sentence adds value: the first states the action, the second details the output format, and the third clarifies the return type. There is zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, annotations cover safety, and an output schema exists), the description is complete. It explains what the tool does, what information it provides, and the return type, which is sufficient for an AI agent to understand and invoke it correctly without needing additional details from structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description correctly omits parameter details, making it appropriately focused. A baseline of 4 is applied as it efficiently handles the zero-parameter case without unnecessary information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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) and resource ('OrbStack Linux 机器' - OrbStack Linux machines), and distinguishes it from siblings like orbstack_machine_info (which gets detailed info for one machine) and orbstack_machine_create/delete (which modify machines). It specifies the scope is all machines with their status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating it lists all machines and their status, suggesting it's for inventory/overview purposes. However, it doesn't explicitly state when to use this versus alternatives like orbstack_machine_info (for details on a specific machine) or orbstack_status (for overall OrbStack status). The context is clear but lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![orbstack-mcp MCP server](https://glama.ai/mcp/servers/heresun/orbstack-mcp/badges/card.svg)](https://glama.ai/mcp/servers/heresun/orbstack-mcp)

Score Badge

Copy to your README.md:

[![orbstack-mcp MCP server](https://glama.ai/mcp/servers/heresun/orbstack-mcp/badges/score.svg)](https://glama.ai/mcp/servers/heresun/orbstack-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/heresun/orbstack-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server