docker-mcp-server
Server Quality Checklist
Latest release: v2.2.5
- Disambiguation4/5
Each tool has a distinct purpose with cross-references clarifying differences, but the sheer number of closely related operations (e.g., compose_stop vs compose_down vs compose_kill; container_stop vs container_pause vs container_kill) creates some risk of misselection. Descriptions are detailed enough to resolve most ambiguity.
Naming Consistency5/5All tools follow a consistent <domain>_<verb> pattern (e.g., container_stop, image_pull, service_create, network_connect). Even subdomains like buildx, compose, and swarm maintain the same convention, making the naming highly predictable.
Tool Count1/5With 156 tools, the server vastly exceeds even the 50+ threshold for 'extreme mismatch'. While Docker has a broad API, the sheer number of tools overwhelms agent context and tool selection, and many are niche (e.g., scout_*, buildx_history_*, context_*). A more curated set covering core workflows would be far more usable.
Completeness5/5The server covers the Docker surface exceptionally well: containers, images, networks, volumes, swarm, compose, buildx, registry, secrets, configs, contexts, plugins, and security scanning. Missing operations are rare (e.g., no single 'system prune', but individual prunes cover it), and most domains have full CRUD plus operational tools.
Average 4.9/5 across 156 of 156 tools scored. Lowest: 4.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 2 community issues answered or closed in the last 6 months
- 145 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
Tools from this server were used 2 times in the last 30 days.
This repository includes a glama.json configuration file.
This server has been verified by its author.
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
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond the sparse annotations: lazy rebuild on next use, the difference from system_reconnect, and that closing connections does not affect running containers. It stops short of explaining idempotence (what happens if already closed) or required permissions, but the provided context is valuable for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with each sentence serving a distinct purpose: action, usage, alternative, special case, side effect, and return value. No filler or wordiness is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool, the description covers most important aspects: purpose, usage, side effects, and return value. However, the unsupported `host` parameter confuses the context and the tool's actual signature, leaving an agent uncertain whether parameters should be passed. This undermines completeness despite the otherwise thorough explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema declares zero parameters with 100% coverage, yet the description repeatedly references a `host` parameter and its omitted behavior. This introduces a parameter that does not exist in the schema, actively misleading an agent. The description adds no correct parameter semantics beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Close and drop pooled Docker client connection(s)". It clearly distinguishes this tool from siblings by noting the lazy rebuild behavior and explicitly contrasting with system_reconnect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: "Use this to force a stale or errored connection to be discarded." It also names an alternative: "Prefer `system_reconnect` when you want to immediately re-establish the connection..." and explains the host omission nuance, offering clear decision-making context.
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 indicate readOnlyHint=false and destructiveHint=false, and the description aligns with that. It adds valuable behavioral context: it re-applies PreviousSpec, raises ValueError if no PreviousSpec, and explains the low-level API mechanism. It also discloses the return format (dict with Warnings key), providing transparency beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and efficiently covers behavior, error condition, implementation notes, args, and returns. It is slightly wordy (implementation detail about APIClient), but every sentence adds useful information and no content is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description covers the essential aspects: what it does, how it works, potential error, and return value. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must define the parameter. It clearly states 'id_or_name - The service id or name', which fully explains the single parameter. This compensates for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Roll a swarm service back to its previous spec', explicitly naming the docker equivalent. It distinguishes itself from siblings like service_update and service_scale by focusing on reverting to a prior spec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (when a rollback is needed) and states a precondition (PreviousSpec must exist, otherwise ValueError). It does not explicitly name alternative tools for exclusions, but the context is sufficient to avoid confusion with service_update or service_scale.
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=false and destructiveHint=false, and the description adds complementary context: "without restarting it," the deprecation of links ("legacy feature... prefer DNS aliases"), and the reversibility via network_disconnect. It does not discuss error conditions or prerequisites like network existence, but adds solid value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then usage context, parameter behavior, and a formatted args list plus return type. There is minor redundancy (aliases, ipv4, links appear in both prose and args list), but each mention serves a distinct purpose: prose explains behavior, args list provides quick reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters with 0% schema coverage, the description covers purpose, when-to-use, all parameter semantics, return value (bool), and the undo path. Gaps include explicit prerequisites (network must exist, container must be running) and error behavior, but overall it is highly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden and succeeds: the args section documents all 8 parameters with meaningful one-liners. Prose adds deeper semantics for aliases (extra DNS names), ipv4/ipv6 (specific IP or driver-assigned), and links (deprecated), fully compensating for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: "Attach a running container to an additional network without restarting it." This clearly distinguishes the tool from siblings like network_create (creating networks), network_list/inspect, and network_disconnect, which is explicitly named as the undo operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: "Use this to give a container access to services on a network it was not started with." It also directs users to network_disconnect for undoing. However, it does not state explicit when-not scenarios or alternatives such as connecting during container creation via container_run.
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 indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral details beyond this: it always disables TTY, defaults to detached mode with container removal, and creates a new container for each run. It does not mention auth/error behavior, but the disclosure of the --rm default and the new-container semantics is significant and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: a one-sentence purpose, two sentences of behavioral context, a complete args list, and a return type. Every sentence adds value and there is no redundant or fluff content. The structure is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description specifies the return dict with fields (returncode, stdout, stderr, truncated). It covers all parameters, key behavioral defaults, and the MCP-specific TTY constraint. Minor gaps include not elaborating on what 'truncated' means or how detached mode affects stdout/stderr, but these are acceptable given the overall richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description contains a complete 'args:' section explaining all 13 parameters in meaningful terms. Examples include noting that command runs in exec-form unless a shell is invoked, project_dir is copied if no local plugin, and timeout_seconds defaults to 600. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Run a one-off command against a compose service.' It also explicitly differentiates from compose_exec by stating that it starts a NEW container rather than running inside an existing one, making its 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear behavioral context: always passes -T, defaults to detached with --rm, and explicitly contrasts with compose_exec. It implies the intended use case (one-off commands in a new container) but does not explicitly list alternative tools or say when not to use it, falling just short of a 5.
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?
With annotations already indicating a mutating but non-destructive operation, the description adds valuable context: it clarifies the resume-from-frozen behavior and the non-raising exit strategy. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: purpose first, then comparisons, then error behavior, then parameters, then return value. No fluff, though the args list could be slightly more concise; each sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing compose tool with 4 optional parameters and no output schema, the description covers the operation, alternatives, error behavior, parameter semantics, and return format. It leaves out prerequisites like project existence but that's inferable from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description compensates by explaining each parameter's purpose (services, project_dir, files, project_name) with defaults and special notes (e.g., project_dir copied to target host if no local plugin). This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure: 'Unpause the containers of a compose project'. It clearly distinguishes from compose_pause (reverse) and compose_start (counterpart for stopped containers), 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool versus alternatives: 'Reverse of compose_pause' and 'compose_start is the counterpart for stopped containers'. Also provides guidance on error handling (does not raise on non-zero exit) which informs proper invocation.
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 discloses important behavior: it always runs detached to avoid blocking the server, and explains the optional wait behavior. Annotations (readOnlyHint=false) align with the mutating nature of starting containers. The description adds transparency beyond the annotations by clarifying the detach behavior and how to ensure readiness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured. It starts with a clear one-liner, then lists parameters in a consistent format without unnecessary verbosity. Every sentence adds value, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (10 optional parameters), the description covers all parameters and provides sufficient behavioral context. It also specifies the return format (dict with returncode, stdout, stderr, truncated). However, it does not elaborate on error handling or edge cases, but this is not essential for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description compensates by explaining each parameter concisely. For example, 'pull' is explained as 'Pull strategy; omit to use each service's own pull_policy', and 'wait' is defined as 'Block until services are healthy'. This provides meaningful semantics for all parameters without relying on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bring up a Docker Compose project, detached.' It distinguishes itself from sibling tools like compose_start by focusing on bringing up the project and explicitly mentioning the detached mode, which is a key behavioral difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical usage guidance: it notes that the command always runs detached, suggests using 'compose_ps' to confirm services are running, and mentions the 'wait' parameter to block until healthy. This gives clear context on when and how to use the tool, though it could explicitly contrast with compose_start or compose_run for stronger differentiation.
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 only convey readOnlyHint=false and destructiveHint=false, so the description carries the burden. It adds valuable behavioral details: from_file is read by server's user, ~ expansion, streaming to daemon, base64 encoding of in-band data, and the path must already exist. It does not mention overwrite semantics or error cases, but overall is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise summary, then additional context, then a clear args block. Each sentence adds value, and the formatting aids readability without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's core behavior, parameter constraints, and return type, and references the inverse operation. It lacks explicit explanation of error handling when both/neither of data/from_file is provided, but overall it is sufficiently complete given the output schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'args' section explains every parameter beyond the schema, describing id_or_name as container id/name, path as requiring existence, data as tar bytes, and from_file as a server host path. It also clarifies the 'exactly one' constraint, fully compensating for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Upload a tar archive to a path inside a container' with specific verb and resource. It also distinguishes itself as the 'Inverse of container_archive_get', differentiating it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete guidance on when to use each input mode ('preferred for large archives' for from_file) and enforces the mutual exclusivity of data/from_file. It implicitly contrasts with container_archive_get but does not explicitly list exclusion scenarios or alternatives.
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?
Even with annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral detail: 'The image id stays the same and no data is copied — a tag is an alias,' and 'image_remove on a tag merely untags while other names remain.' It also discloses the return value, going well beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well organized: a one-line definition, a short explanatory paragraph, and a clear args/returns list. Every sentence contributes useful information with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tagging tool with 4 params and 2 required, the description covers purpose, behavior, parameter semantics, return value, and relationship to push/remove. It provides enough context to select and invoke the tool correctly without needing the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining id_or_name as source, repository with a registry-qualified example, and tag default. However, 'force - Force the tag' is tautological, and the stated default 'latest' conflicts with the schema's default null, creating ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence precisely states the action: 'Tag an image into a repository (add a name to an existing local image).' It distinguishes tagging from copying/pushing and clearly differentiates from sibling tools like image_push and image_remove by clarifying it only creates an alias.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Typical flow: tag with the registry-qualified name, then image_push,' and notes that image_remove on a tag merely untags. It establishes when to use tagging relative to push/remove, though it does not explicitly list alternative tools for retagging or state 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by disclosing the manager requirement ('Must run against a swarm manager') and detailing the information returned ('Shows role, availability, status, and manager reachability' and 'returns: dict - The node's attrs'). This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a prerequisite/alternatives sentence, and explicit args/returns sections. It is slightly verbose due to the multiple alternatives in one long sentence, but every part contributes useful context. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description is fairly complete: it covers purpose, prerequisite, parameter meaning, return structure, and related tools. It does not discuss error handling or authentication, but those are less critical given the annotations and the straightforward nature of an inspect operation. It ranks above average for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no description for the only parameter (schema coverage 0%), so the description must compensate. It does so effectively: 'args: id_or_name - The node id or hostname (as shown by node_list).' This clarifies the accepted values and provides a reference for obtaining them. The description adds sufficient meaning beyond the bare type 'string'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get a swarm node's full inspect payload by id or name.' This clearly distinguishes it from sibling tools like node_list (which enumerates nodes) and node_update (which modifies nodes). The mention of 'full inspect payload' further differentiates it from other inspect tools by specifying the swarm node scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a prerequisite: 'Must run against a swarm manager.' It also provides alternatives: 'use node_list to enumerate nodes first, or the docker://nodes resource for a fleet summary; service_ps(filters={"node": ...}) shows what a service runs on one node.' This gives clear guidance on when to use this tool versus related tools, satisfying the 'when vs alternatives' requirement.
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 indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds valuable behavioral context by explaining that force=True 'bumps the ForceUpdate counter' to trigger redeployment, and it states the return type. This goes beyond the basic hints and gives the agent a clearer expectation of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose sentence, followed by a succinct explanation of the two modes, then a compact args list. There is no filler or repetition. Every sentence adds information, and the structure makes the material easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex tool with nested objects and a boolean return, the description covers the purpose, the two mutually exclusive parameter sets, the behavior of force redeploy, and the return value. Given that an output schema exists for the bool and annotations are present, this is a complete picture for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description takes on the full burden of documenting parameters. It provides an args section that explains id_or_name, updates, and force, and clarifies the mutual exclusivity constraint. The 'updates' field is described as using 'same parameters as service_create', which requires a cross-reference but is still actionable. This meaningfully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Update a swarm service's configuration, or force a redeploy with no spec change.' This clearly distinguishes the tool's core purpose from siblings like service_scale or service_rollback. The two operational modes are explicitly named, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance for the tool's two modes, including the 'exactly one of updates/force' constraint and a concrete real-world example for force redeploy (rescheduling after a node change or re-pulling a mutable tag). However, it does not explicitly contrast with alternative sibling tools (e.g., service_scale), so it misses an explicit exclusion statement.
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 only include readOnlyHint=false and destructiveHint=false, so the description carries the transparency burden. It discloses that `-T` is always passed (no TTY) and warns that `sh -c` interprets shell metacharacters in untrusted substrings. It also documents the return dict and timeout default, adding useful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence purpose, two behavioral caveats, then a tidy parameter list. No wasted words, and all content is relevant to selecting and invoking the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, a nested env object, and no output schema, the description covers return values, default behavior, multi-replica indexing, and shell-safety guidance. It provides a complete operational picture for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the tool description fully compensates by listing all 10 parameters with clear explanations, defaults, and special semantics such as `project_dir` copying and `index` for replicas. This is exactly the information an agent needs to fill parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Run a command inside an already-running compose service container', which names a specific verb and resource scope. It also references `container_exec` as a related tool, helping to position this tool relative to a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear this tool targets compose-managed service containers and mentions `container_exec` as an alternative, but it does not explicitly state when to prefer one over the other. It does give concrete execution guidance about using exec-form argv versus `sh -c` forms to handle shell metacharacters.
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 and destructiveHint=false, and the description adds valuable behavioral details such as raising RuntimeError on CLI failure and returning parsed JSON dicts per project. It also clarifies the 'all' parameter includes stopped projects, going beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the core purpose. Each line adds necessary information: purpose, scope, alternative, error behavior, parameter meaning, and return format, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description is complete. It covers what the tool returns, how the output is parsed, the effect of the only parameter, error behavior, and how it relates to sibling tools, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully explains the only parameter 'all' as 'Include stopped projects.' It also documents the return format ('list - One dict per project'), which compensates for the lack of schema descriptions and output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists compose projects known to the daemon across all directories, specifying a project-level view with one entry per project. It distinguishes itself from compose_ps, which lists containers of a single project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (listing projects at the project level) and explicitly references compose_ps as the alternative for viewing containers of a single project. It does not list extensive exclusions, but the guidance is sufficient for a simple listing tool.
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 readOnly and non-destructive behavior. The description adds that RuntimeError is raised on CLI failure and describes the return dict structure (Name, Endpoints with daemon URL), which goes beyond annotations to set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with separate args/returns sections. Every sentence contributes value, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description covers purpose, sibling differentiation, error behavior, parameter sourcing, and return keys. It is complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by explaining the 'name' parameter and instructing to source it from context_list's Name field. This adds meaningful semantic context beyond the raw string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (return full configuration) on a specific resource (single Docker context), and explicitly contrasts with context_list to distinguish scope. This provides unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It points to context_list as the alternative for one-line summaries and instructs to use the Name field from context_list, which gives practical guidance. However, it doesn't enumerate other possible alternatives (e.g., context inspect vs other inspect tools) but the differentiation is strong.
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 the annotations, which only indicate non-read-only and non-destructive. It discloses a security risk: `auth_config` may be logged verbatim by MCP clients, and recommends using host `docker login` to reuse cached credentials. It also explains the behavior of bare repository names (pushing to Docker Hub) and the need for pre-tagging. This is crucial for safe and correct use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized but every sentence contributes value: action, prerequisite, auth, security warning, and parameter list. It is front-loaded with the core purpose and structured logically. Not overly verbose, but the args section could be more integrated; still, it earns its place by clarifying parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a push operation with authentication requirements, the description covers the necessary steps, security considerations, and return type. It mentions the return value ('Push output as a string') and provides prerequisites. Despite not describing error cases, it gives enough context for an agent to invoke the tool correctly, especially with the existing annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description's args section is essential. It provides one-line meanings for each parameter: repository (image repository), tag (tag to push), auth_config (optional registry auth). While it doesn't delve into formats or edge cases, the earlier prose clarifies that repository should be registry-qualified and tag is optional. This compensates for the schema's lack of descriptions, though it could be more detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Push an image or repository to a registry.' It uses a specific verb and resource, and distinguishes itself from sibling tools like image_pull and image_tag by clarifying that it uploads an already-tagged image to a remote registry. The prerequisite about tagging first reinforces the specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: the local image must be pre-tagged with the target name, bare names push to Docker Hub, and private registries require credentials. It also recommends using `docker login` over `auth_config` for security, but does not explicitly contrast this tool with alternatives (e.g., when to use `image_pull` or `registry_tags`). The guidance is clear and actionable, but lacks explicit exclusions or comparative 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?
Annotations already indicate this is destructive (destructiveHint=true). The description adds valuable behavioral context: the need to drain first, the force flag's effect on active nodes, and the boolean return value. It could mention error behavior or permissions, but the key behaviors are disclosed beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose statement, usage/context note, args list, and return type. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with an output schema, the description is sufficiently complete. It covers the normal workflow, the force exception, and the return value. It omits error scenarios (e.g., node not found) but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It clearly explains id_or_name (node id or name to remove) and force (force removal of active/reachable node), adding significant value beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a node from the swarm', which is a specific verb+resource statement that clearly distinguishes this from sibling tools like node_inspect, node_list, and node_update. The purpose is immediately unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it instructs to drain the node with node_update and have it leave before removal, and explains that force=True is required for active/reachable nodes. This is excellent context for selecting the correct approach and references the relevant sibling tool.
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 mark the tool as read-only and non-destructive. The description adds valuable behavioral context: multi-hop resolution (manifest -> platform entry -> config blob), stripping of `:tag`/`@digest` from repository, default platform behavior, and credential override behavior. It also discloses the return format. This goes beyond the annotation's simple safety profile, though it does not cover failure modes or 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded. The opening sentence states the core function, followed by a useful list of extracted fields, then a brief explanation of resolution hops. The `args` list is clear and the `returns` note completes the picture. Every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only registry inspection tool with no output schema, the description provides complete context: purpose, parameter semantics, multi-platform resolution, credential handling, and the exact return dictionary. It is self-contained and leaves the agent with sufficient information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has zero descriptions (0% coverage), the description's `args` section thoroughly documents all five parameters: repository, reference, platform, username, and password. It explains defaults, overrides, and special behaviors such as '`:tag`/`@digest` is stripped — pass via `reference`'. This fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Fetch and parse an image's config blob from a registry without pulling.' It then enumerates the exact contents (env vars, entrypoint, cmd, workdir, ports, user, labels, layer history) and explicitly contrasts with sibling `registry_manifest`, which only points at the config digest. This makes the tool's purpose unmistakable and distinguishes it from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to inspect an image's configuration without pulling it, and explicitly contrasts with `registry_manifest`. It also provides context about multi-platform resolution and auth overrides. However, it does not explicitly state when not to use this tool or name alternative tools like `image_inspect` or `image_registry_data`, leaving some room for ambiguity.
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?
Annotations already indicate destructiveHint, but the description adds important subtle behavior: removal does not immediately affect running service tasks; they retain access until restarted/updated. This is valuable context that goes beyond the annotation and helps set expectations 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, followed by behavioral nuance and a structured args/returns block. Each sentence earns its place; the second paragraph is slightly long but provides necessary detail on removal semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, a bool output schema, and annotations, the description covers all essential aspects: purpose, prerequisite, side-effects, parameter meaning, and return value. The inclusion of helper tool references makes it self-contained and practically complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description, but the description compensates by explaining that id_or_name accepts either a secret id or name. This clarifies the parameter's flexibility and purpose beyond the bare schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a Swarm secret' using a specific verb and resource. It is clearly distinguished from sibling secret tools like secret_create, secret_inspect, and secret_list, which handle other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit pre-removal guidance: use service_list and service_inspect to identify services mounting the secret, and notes that service filters don't support secret reference. The 'requires a swarm manager' line sets a prerequisite but doesn't explicitly contrast with alternatives in terms of when not to use this tool.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains the safety-critical behavior: the rebuilt client is validated before the old one is closed, so a failed rebuild preserves the working client. It also discloses the limitation about not retargeting daemons and explains the return shape. This adds meaningful behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, starting with the core purpose and then adding important behavioral details in a logical order. It is concise enough given the amount of necessary context, and every sentence contributes meaning—no filler or repetition of schema/annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description covers all necessary bases: what it does, why it exists, safety behavior, limitations, alternatives, and return value shape. It is fully self-contained and leaves no important gap in the agent's understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema declares zero parameters, but the description references a `host` parameter ('Rebuilds the default host's client when `host` is omitted'), which is misleading given the schema. With no parameters defined, the description should not imply an optional parameter that cannot be passed. This creates ambiguity about how to invoke the tool and undermines the otherwise clear semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific action: 'Rebuild a pooled Docker client from its configured endpoint, to recover a wedged connection.' It distinguishes itself from related tools by explicitly mentioning system_close and host_list, and by stating what it cannot do (retarget to a different daemon). This gives a precise verb+resource+scope definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit use case ('to recover a wedged connection'), tells the user when not to use it ('CANNOT retarget to a different daemon'), and names alternatives: edit DOCKER_MCP_SERVER_HOSTS for adding/changing daemons, system_close for closing without rebuilding, and host_list for showing endpoints. This is excellent when-to-use vs. when-not-to-use guidance.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context without contradicting annotations. It discloses truncation behavior, partial-record dropping, error raising (RuntimeError), and the workaround for exhaustive output. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for a tool with notable caveats. It front-loads the core purpose, then provides practical warnings and finally structured arg/return notes. Every sentence adds value, and the layout is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, no output schema, and moderate complexity, the description covers the essential aspects: what it reports, how it might fail, how to get complete results, error behavior, parameter semantics, and return format. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no description for the builder parameter, so the description's 'args: builder - Override the active builder' is essential and adds meaning. It also documents the return type as 'list - One dict per cache record'. With only one parameter, this is sufficient compensation for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Report BuildKit cache disk usage as a list of records.' It clearly differentiates from siblings by contrasting with system_df ('covers daemon-side disk, not builder cache') and buildx_prune ('Reclaim the cache').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context, explicitly noting when the tool may be insufficient (large caches exceeding MAX_CLI_OUTPUT_BYTES) and suggesting a host-side command for exhaustive reporting. It also directs to buildx_prune for reclaiming cache and clarifies that system_df is not a substitute. However, it does not explicitly enumerate alternative tools for the same job.
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 mark it read-only and non-destructive. The description adds important behavioral context: it uses the docker CLI's credential store, supports OCI indexes/attestations, and explains how `raw`/`format` change the output. It could mention whether a daemon is required, but the added value is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a comparative context paragraph, a concise args list, and a return contract. No redundant sentences; each part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only nature, 4 parameters, and no output schema, the description covers the essentials: purpose, parameter meanings, return dict, and raw/format behavior. It lacks explicit error conditions or prerequisites like buildx installation, but is still fairly complete for an inspect tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, but the description documents all four parameters: image with concrete examples, raw and format with their semantics and mutual exclusivity, and builder as an override. This fully compensates for the schema's silence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states the action and resource: 'Inspect a manifest in a registry without pulling.' It also distinguishes from siblings by referencing `docker manifest inspect` and `registry_manifest`, making its niche clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides direct alternatives: 'Replaces `docker manifest inspect`' and '`registry_manifest` answers the same question over direct HTTPS with no daemon or plugin.' This gives clear when-to-use guidance and context for choosing between tools.
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` and `destructiveHint: false`, so the safety profile is covered. The description adds valuable behavioral details like raising RuntimeError on CLI failure and the nuance that `project_dir` may be copied to the target host if no local plugin. It does not contradict 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, usage, args, returns). Every sentence adds value, though the 'Answers...' sentence slightly overlaps with the first line. It remains compact given the parameter details and contextual notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 0% schema param coverage, the description fully specifies parameters, return values, error behavior, and prerequisites. It also references related tools and edge cases (e.g., container existence, plugin copy behavior), making it complete for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by documenting all four parameters with meaningful explanations: `project_dir` (default and copy behavior), `files` (repeatable `-f`), `project_name` (override), and `services` (restrict/default). It also explains the return format, making the parameters and output fully understandable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists compose project service images, parsed via `--format json`. It distinguishes from sibling tools by specifying the exact question it answers ('what image and tag does each service container actually run?') and contrasts with `compose_ps` and `image_list`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: when to use (to get actual image/tag per container), prerequisites (containers must exist via `compose_up`/`compose_create`), and alternatives (`compose_ps` for state, `image_list` for daemon-wide). This covers both when and when-not.
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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it blocks until timeout, kills the subprocess on timeout (TimeoutExpired), returns exit codes on stdout, and notes the project_dir copy behavior. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence purpose, followed by usage notes and a structured args block. It's a bit long but every section earns its place—especially given the lack of schema descriptions. The formatting is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a medium-complexity tool with 5 parameters and no output schema, the description covers everything needed: purpose, usage context, parameter semantics, timeout behavior, and return value format. It even distinguishes from related tools. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates with an args section explaining each parameter: services (required), project_dir (default server cwd, copied to target if no plugin), files (repeatable), project_name (override), timeout_seconds (default 300). This adds meaning that the schema alone lacks, and even covers nuance like the plugin copy behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states precisely what the tool does: blocks until named service containers stop and returns their exit codes. It clearly identifies the resource (compose services) and the action (wait), and explicitly differentiates from sibling tools like container_wait and service_wait.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool: for one-shot/batch services, and warns about long-running services with timeout_seconds. It even names alternatives: 'For a single container use container_wait; for swarm services use service_wait.' This is exemplary usage guidance.
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?
Beyond the annotations (destructiveHint=true), the description discloses that a swarm manager is required, the tool fails if services reference the config, and it is the final step in a config rotation flow. It also clarifies the return type (bool) and the condition for success, providing significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a single primary purpose sentence. It then provides essential prerequisite and flow context, followed by a clear args/returns section. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool, the description covers the key aspects: what it does, prerequisites, failure conditions, and the argument meaning. It references config_create for the broader workflow, making it complete within the tool family context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a string parameter named id_or_name with no description. The description adds semantic value by specifying that this is 'The config id or name,' clarifying that either identifier can be used. It also documents the return value, which is useful despite the output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a swarm config,' a specific verb+resource that clearly distinguishes this tool from its siblings config_create, config_inspect, and config_list. It also adds context about being the last step of a rotation flow, reinforcing its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the requirement for a swarm manager and explicitly warns that removal fails while services still reference the config, advising to update or remove those services first. This provides clear when-to-use and when-not-to-use guidance, though it does not explicitly name alternative tools.
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 and destructiveHint=false, so the bar is lower. The description adds value by enumerating the exact categories of data returned (config, state, network settings, mounts, env vars, resource limits) and noting equivalence to `docker inspect`, which gives useful behavioral context beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a purpose sentence, usage paragraph, and args/returns sections. It is slightly wordy—e.g., 'full inspect detail' and 'complete information about one container' are redundant—but every sentence otherwise serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple scope (one parameter), good annotations, and absence of an output schema, the description is complete. It tells what the return value is ('dict - Full container inspect attrs'), how to invoke it, and how it relates to siblings, leaving little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining the sole parameter: 'id_or_name - Container id (full or short) or name'. This adds meaning beyond the bare schema type (string) and gives clear format expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Return the full inspect detail for a single container', specifying the resource and scope. It explicitly differentiates from siblings by naming `container_list`, `container_logs`, and `container_stats`, 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Use this when you need complete information about one container' and directly names alternatives for other cases ('To enumerate many containers use `container_list`', 'For just logs or stats use `container_logs` / `container_stats`'). This is excellent usage direction.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: the resolved daemon URL semantics, the meaning of `read_only`, `non_destructive`, `tls`, and `default` fields, and the mirror resource. It also discloses the `null` URL behavior for docker-py platform default, going well beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense with no filler. It front-loads the primary purpose in the first sentence, then uses a compact paragraph plus a bulleted return format. Every sentence adds value—behavioral nuances, integration with other tools, and return field meanings—without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers all necessary context: source of hosts, single vs multiple resolution, default fallback, and how to use the result with other tools. It even explains the return dict fields and the mirror resource, making it self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter schemas to clarify. The description compensates by explaining the concept of the `host` argument used by other tools, which gives context for the list. It doesn't need to describe parameter syntax because none exist, but it effectively explains the relevant selection semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the Docker hosts configured via DOCKER_MCP_SERVER_HOSTS', a specific verb+resource combo that clearly states the tool's function. It further distinguishes itself from daemon-backed tools by explaining how the `host` argument selects from the listed hosts, setting it apart from siblings like `system_ping`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by explaining the single-host vs multi-host behavior and how the `default` entry is used when `host` is omitted. It also tells the user how to use the output with other tools ('pass a name as the `host` argument of daemon-backed tools'). It lacks explicit 'when not to use' exclusions, but provides strong situational guidance.
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 and destructiveHint=false, so the safe read nature is covered. The description adds behavioral details beyond that: it lists the exact fields returned (`Id`, `Created`, `CreatedBy`, `Size`, `Comment`), explains the meaning of `<missing>` Ids, and notes the result is ordered newest first. This gives the agent a clear picture of the output without overstating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Each sentence adds value: use-case justification, field details, an alternative tool pointer, and a terse args/returns summary. There is minimal redundancy and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single parameter and no output schema, the description provides complete contextual information: what the parameter accepts, what the return type is, the fields included, ordering, and edge-case behavior (`<missing>` for imported layers). It also positions itself against `image_inspect`, making its role within the toolset clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides a bare string parameter with no description (coverage 0%). The description compensates by explaining 'id_or_name - Image name (with optional tag/digest) or id', which defines the acceptable input format. This is sufficient for one parameter and clearly aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Return the layer history of an image', using a specific verb and resource that clearly states the tool's function. It also distinguishes from siblings by explicitly directing users to `image_inspect` for full metadata, making its unique scope apparent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context ('Useful for auditing what commands built each layer and diagnosing image size') and explicitly names an alternative ('For full image metadata use `image_inspect` instead'), making it obvious when to use this tool versus a sibling.
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 and destructiveHint=false, covering safety. The description adds valuable behavioral context: it details what the inspect result includes (connected containers with IPs, IPAM config, driver options) and states the return is equivalent to `docker network inspect`. This goes beyond the annotations by explaining output contents and performance tradeoffs, though it doesn't cover error cases or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, followed by useful detail and a structured args/returns section. Every sentence earns its place, with no filler or repetition. The layout is logically organized and scannable, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-parameter inspection tool, the description is complete. It states what the tool does, what data is included in the response, the return type, and when to use an alternative. The lack of an output schema is mitigated by the explicit mention of return structure and contents, making this sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides the essential param explanation: 'id_or_name - The network id or name.' This fully compensates for the bare schema field, clearly indicating the parameter accepts either an ID or a name. It adds the exact semantic meaning needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Return the full inspect detail for a single network,' which is a clear, specific verb+resource statement. It differentiates from siblings like network_list by explicitly contrasting the 'quick overview of many networks' use case, making the tool's 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance: 'For a quick overview of many networks use `network_list` instead — its default (non-`greedy`) response omits the per-network `Containers` detail for speed.' This tells the agent when to use this tool versus an alternative, which is exactly the kind of usage direction needed.
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 goes well beyond annotations by detailing side effects: plugin remains installed, existing containers unaffected, new containers cannot use it, and force may disrupt active containers and cause loss of access to plugin-provided resources. This is rich behavioral disclosure that annotations (readOnlyHint=false, destructiveHint=false) do not capture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary, two sentences of behavioral detail, explicit args and returns. Each sentence delivers essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema (bool return), the description is complete. It covers purpose, side effects, parameter semantics, return type, and even points to plugin_enable for reversal. No major gaps exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It explains 'name' as plugin name (adequate) and 'force' with meaningful semantics: 'Disable even if active containers are using the plugin (may disrupt them).' This adds practical meaning beyond the schema's raw boolean. A tad more detail on name (e.g., use plugin_list) would push it higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Disable a plugin so it stops intercepting Docker API calls; the plugin remains installed.' It clearly distinguishes the operation from related siblings like plugin_enable (re-enable) and plugin_remove (removal), and states the resource remains installed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use context: disabled plugins affect new containers but not existing attached ones, and force=True is recommended for active containers. It also explicitly mentions the alternative 'Re-enable with plugin_enable.' However, it does not cover all possible alternatives (e.g., plugin_remove) or when not to use this tool, so a small gap remains.
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 and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by stating it returns 'the full attrs... including Enabled and Settings', and it frames usage around inspecting state before mutations. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences. The first sentence states the core purpose, the second provides usage context and alternatives, and the final two give parameter and return details. Every sentence earns its place, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only tool with no output schema, this description is complete. It covers purpose, usage scenarios, alternatives, parameter semantics, and return value expectations. It tells the agent everything needed to invoke it correctly and interpret results, given the simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only has a required 'name' string with no description, so 0% schema coverage. The description compensates by defining the parameter: 'args: name - Plugin name, e.g. "vieux/sshfs:latest"' plus a concrete example. This adds meaningful semantic info that the schema lacks, though it doesn't specify any format constraints or possible values beyond the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Return the full attrs for a single installed plugin,' which is a specific verb+resource statement. It clearly distinguishes from sibling plugin_list by saying 'For the set of all installed plugins use plugin_list.' It also mentions the return includes Enabled and Settings, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to check a plugin's Enabled state before calling plugin_enable / plugin_disable, or to read the config keys it exposes under Settings.Env before calling plugin_configure.' It even names the alternative tool plugin_list for when you need all plugins. This provides clear when-to-use guidance and alternatives.
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 only indicate non-read-only and non-destructive. The description adds valuable behavioral context: the daemon handles permission grants non-interactively, so users must proactively check privileges. It also specifies the return value structure, which is absent from annotations. Slightly lacking on failure modes or what happens if the plugin already exists, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured: main action, workflow guidance, then arguments/returns. It avoids unnecessary fluff, though the workflow narrative could be tightened without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description covers the action, prerequisites, parameter formats, return type, and post-install steps. It effectively situates the tool within the plugin lifecycle, making it self-contained for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), but the description fully compensates. It explains `remote` with an example (vieux/sshfs:latest) and `local_name` as an alias defaulting to remote, making both parameters clear and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Install a plugin from Docker Hub', a specific verb and resource. It clarifies the remote reference format and distinguishes itself by outlining the install->inspect->enable workflow, which clearly separates it from sibling plugin tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs users to call plugin_privileges first to inspect permissions, then details post-install steps (plugin_inspect, plugin_enable, plugin_configure). It also notes alternatives like plugin_list and plugin_remove, providing clear usage context and a recommended sequence.
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 and destructiveHint=false, so safety is clear. The description adds behavioral context about the Enabled key and return contents, which is useful beyond annotations. It does not need to mention side effects since this is a read-only list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: first sentence gives the verb/resource, second clarifies scope with an exclusion, third provides usage guidance and return format. Compact, well-structured, and no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no parameters, the description fully covers the return shape and the state key semantics. It also contextualizes the tool within the plugin lifecycle, making it complete for an agent to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so baseline is 4. The description compensates by detailing the return attrs (Id, Name, Enabled, Settings, Config), which helps the agent understand what the list will contain without an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States exactly what it does: 'List installed engine plugins with their full attrs.' It distinguishes engine plugins from Docker CLI plugins and names the related sibling tools (plugin_inspect, plugin_enable, etc.), making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: 'Use it to find exact plugin names for plugin_inspect/plugin_enable/plugin_disable/plugin_remove.' Also clarifies what it does not cover (Docker CLI plugins), giving a clear boundary and aiding tool selection.
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=false and destructiveHint=false, so the description's added value is the precondition about swarm manager and the return value description. It mentions it creates a service and returns the full document, but it doesn't elaborate on side effects like image pulls or synchronous vs asynchronous behavior. Still, with annotations covering the basic mutation safety profile, the description provides decent additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but information-dense. It is front-loaded with the core purpose and prerequisite, and the extra_kwargs examples are useful rather than filler. The structure (description → args → returns) is logical. Every sentence contributes value, though the extra_kwargs list could arguably be shortened for absolute conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool like service_create with no output schema, the description covers all key aspects: purpose, prerequisites, alternative tools, parameter details with examples, and return type. It appropriately points to docs_lookup for edge cases, making it a complete guide for an agent to invoke the tool correctly. This is a genuinely comprehensive description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates. It explains each parameter: image with example, command with allowed types, and extra_kwargs with a detailed list of common keys and example structures. It also advises using docs_lookup for unknown keys, which further guides parameter usage. This exceeds what the bare schema provides by a large margin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Swarm service' with specific verb and resource, and even notes the prerequisite of a swarm manager node. It distinguishes itself from sibling tools like container_run by explicitly mentioning this is for replicated/global scheduling, rolling updates, and automatic restart. This is unambiguous and differentiates from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this instead of container_run when you need replicated or global scheduling, rolling updates, or automatic restart across the swarm.' This gives direct comparison and when-to-use guidance. It also mentions the requirement of a swarm manager node and instructs to use docs_lookup for any other docker-py parameters, preventing guessing.
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 indicate `readOnlyHint` and `destructiveHint` are false, meaning action is expected. The description adds key behaviors: defaults to `detach=True`, re-running with same `name` updates in place, does not raise on non-zero exit, and the actual return value structure. It does not mention side effects like whether it modifies existing services, but the update behavior is covered. This goes beyond annotations, earning a high score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear overview paragraph and a bulleted args list. Every sentence adds valuable information—prerequisites, behavior, usage warnings, and param semantics. It is concise for the complexity involved (8 params) without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations beyond read/destructive hints, the description covers all necessary aspects: purpose, usage, parameter details, return format, and error handling. It also mentions swarm manager requirement and detach behavior, which are critical. The tool is complex, and the description is complete enough for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all 8 parameters. It does: explains `name` (create or update), `compose_files` (repeated `-c`, later override earlier, at least one required), `detach` (immediate vs wait), `cwd` (for resolving relative paths), and others. It also clarifies defaults and nuances that are not in schema, like the `timeout` recommendation. Slightly less detail on `prune` and `with_registry_auth` but still adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Deploy (or update) a stack to the swarm from one or more Compose files.' It uses specific verbs (deploy/update) and identifies the resource (stack, swarm, Compose files). It distinguishes from sibling `compose_up` by explicitly calling it 'The swarm analogue of `compose_up`' and mentions alternative monitoring tools like `stack_services` and `stack_ps`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: requires the daemon to be a swarm manager, explains the detach behavior with a clear recommendation ('set `detach=False` to wait for the rollout (give it a generous `timeout_seconds`)'), and contrasts with `compose_up` and monitoring tools. It also warns that the tool does not raise on non-zero exit, telling users to inspect `returncode`/`stderr`.
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 and destructiveHint=false, so the safety profile is known. The description adds an important operational constraint ('Works on a manager node only') and defines the return type, but does not describe error behavior when invoked on a non-manager node.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each serving a distinct purpose: what it inspects, when to use, and what it returns. It is front-loaded with the primary purpose and contains no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only inspect tool with no output schema, the description fully covers the resource (swarm), the scope (daemon's swarm), the prerequisite (manager node), the return type (dict), and the alternatives. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. The description adds context about the returned data (id, spec, join-token config, CA info), but there are no parameters to explain, meeting the baseline for a 0-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inspects the swarm the daemon belongs to, listing the included fields (id, spec, join-token config, CA info). It also differentiates from sibling tools by explicitly comparing with node_list and swarm_join_tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly specifies when to use: on a manager node for cluster-level configuration. It names direct alternatives: node_list for per-node state and swarm_join_tokens for new node tokens, leaving no ambiguity.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral context beyond that: the tokens are secret bearer credentials, anyone holding the manager token can join as a manager, the result should not be logged, and it always reflects current tokens after a reload. This is substantial and not redundant 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and every sentence earns its place: purpose, usage relationship, security warning, implementation detail, and return format. It is front-loaded with the primary action and remains compact without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter read-only tool, the description is complete. It covers return format, sensitivity, and the relationship to `swarm_join`, leaving no critical gaps. The lack of an output schema is compensated by the explicit dict return description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. The description clarifies the return format (dict with Worker and Manager keys) and token meanings, which is useful given there is no output schema, but there are no parameter semantics to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Return the swarm's worker and manager join tokens.' It clearly distinguishes from siblings like swarm_join (which consumes tokens) and swarm_init (which initializes the swarm), and explains the role in the init -> join loop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that these tokens are required for `swarm_join`, providing clear context for when to use this tool. It also advises treating the result as sensitive and avoiding logging. However, it does not explicitly name alternatives or when not to use it, so it falls slightly short of a 5.
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 behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false): it explains that a locked node cannot serve API requests, that unlocking resumes the manager automatically, and that the key must be retrieved from another unlocked manager. However, it does not mention failure modes like an incorrect key or idempotency, which would have made it more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening purpose, a detailed usage paragraph, and args/returns. Every sentence adds valuable context, though the explanatory paragraph is slightly verbose. Front-loaded with the primary action, it remains clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (swarm autolock and locked manager states), the description is complete: it covers the cause, prerequisites, invocation location, key retrieval method, post-unlock behavior, and return type. The output schema corroborates the bool return, so no further details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines 'key' as a string with no description (0% coverage). The description fully compensates by stating 'key - The swarm unlock key (from swarm_unlock_key)', giving the agent a clear source for the parameter value and its meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Unlock a manager node that is locked after restart due to autolock being enabled.' This clearly states the action and target, and distinguishes it from siblings like swarm_unlock_key (which retrieves the key) and swarm_init/swarm_update (which control autolock).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: when autolock is enabled and a manager node is locked after restart. It specifies where to call the tool ('Must be called on the locked manager node directly'), how to obtain the key (via swarm_unlock_key from any unlocked manager), and explains why other managers must be used (a locked node cannot return its own key). This is exemplary guidance.
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 and destructiveHint=false. The description adds return structure, field names, and notes it follows `docker info` semantics, which is useful behavioral context beyond the annotations. No 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: three sentences front-loaded with purpose, followed by relevant detail and a compact return signature. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only system info tool, this description is fully complete. It explains what it returns, gives a helpful analogy to docker info, and directs to alternatives for adjacent needs. The return dict keys provide sufficient expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so schema coverage is 100% by default and the description doesn't need to explain parameters. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return system-wide Docker information, like `docker info`', with specific examples of returned fields. It distinguishes itself from sibling tools by mentioning the exact alternatives for version and disk usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to use `system_version` for version/API level and `system_df` for disk usage, providing clear guidance on when not to use this tool. The context of 'Daemon runtime state' further clarifies its appropriate use.
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 and destructiveHint=false. The description adds valuable context beyond that: it labels the tool as the 'cheapest' check (performance characteristic), explains failure likely means connection config rather than load, and documents the bool return value. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sections: purpose, usage context with alternatives, and return type. The description is front-loaded with the main verb and uses each sentence to add distinct value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only health check with a bool output schema, the description covers purpose, usage, alternatives, and return semantics. It is fully self-contained and leaves no significant gaps for an agent selecting or invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema confirms this (empty properties, 100% coverage). With no params to document, the description reasonably omits parameter details. Baseline for 0 params is 4; nothing extra needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Check that the Docker server is responsive.' It clearly differentiates from sibling tools by explicitly naming alternatives (system_reconnect, host_list, system_version/system_info), making the tool's unique scope obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: identifies it as the 'cheapest daemon health check,' notes failure usually points to connection config rather than load, and names specific alternatives for different situations (system_reconnect for wedged clients, host_list for endpoints, system_version/system_info for details).
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 and destructiveHint=false, and the description is consistent, adding context about the return format and use case. It doesn't mention further behavioral nuances, but for a simple version-info read, the additional return-value detail is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, adds one line of distinguishing context, and includes a compact return-type hint. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read-only tool, the description is complete: it names the resource, clarifies the difference from sibling `system_info`, and gives expected return fields. No output schema exists, but the inline dict summary fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty with 100% coverage. Since there is nothing to explain, the baseline of 4 applies; no additional parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pairing ('Return Docker server version information') and immediately distinguishes itself from sibling `system_info` by explaining that `system_info` reports runtime state instead. This makes the purpose unmistakable and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('the first thing to check for feature availability') and names an alternative (`system_info`) with its specific purpose, providing clear when-to-use and when-not-to-use guidance.
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 indicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context such as 'Volumes are addressed by name only' and explains how managed_only filters on a specific label. It doesn't contradict the annotations and supplements them with details about return format and filter 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise at ~90 words and well-structured with a brief intro, usage hint, args, and returns sections. Every sentence adds value, but the 'Volumes are addressed by name only' sentence could be seen as slightly tangential; still, it's important context for how to interact with volume entities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description specifies the return format as a list of volume documents with example fields. It covers parameters, return type, and alternative tools, making it complete for a list operation with two parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter descriptions, but the description thoroughly explains both parameters: filters with examples (dangling, name, label) and managed_only with its label-filtering behavior and how it combines with filters. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List volumes' with a specific verb and resource. It distinguishes itself from sibling tools by noting that volume_inspect is for detail and volume_remove/prune are for cleanup, making its purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool vs alternatives: 'feed a Name to volume_inspect for detail or volume_remove / volume_prune to clean up.' It also gives a concrete example of using filters for dangling volumes, providing strong usage guidance.
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?
Annotations already indicate read-only and non-destructive behavior, but the description adds substantial behavioral detail: it parses JSON output, returns a raw fallback when output isn't a JSON object, raises RuntimeError on CLI failure, and explains how ref is normalized. This goes well beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise purpose sentence, a return summary, and a clearly labeled args/returns section. All sentences add necessary information, and the detailed ref explanation is warranted due to the subtle behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with minimal schema and no output schema, the description covers entry point, return shape, error behavior, version requirement, and parameter semantics. It is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero descriptions, but the description fully compensates with detailed param docs: ref explains the qualified vs bare id transformation, the empty/omitted case, and the ^N syntax; builder explains its default and interaction with ref. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Inspect a single build record by ref', clearly distinguishing this from buildx_history_list (listing) and other buildx tools. It further clarifies the exact scope (single record) and the debugging use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly frames the tool as for debugging failed or slow builds found via buildx_history_list, giving concrete context for when to use it. It also mentions the version requirement and error condition, but does not explicitly name alternative tools or state when not to use this tool.
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 and destructiveHint=false. The description adds valuable behavioral context: 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result' and clarifies that stdout is human-readable. This goes beyond basic safety hints, though it could further detail error scenarios for missing builders.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, with clear sections for args and returns. Each sentence adds value: purpose, differentiation, exit code behavior, parameter explanations, and return format. No redundant content is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description is self-sufficient. It specifies the return dict structure, parameter defaults, and non-zero exit behavior, and even points to an alternative for JSON output. This covers all essential context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries the full burden. It documents both parameters: 'name' (defaults to the active builder) and 'bootstrap' (boot if not running), adding semantics that the schema omits. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Inspect a builder instance,' a specific verb+resource statement. It also differentiates from sibling buildx_list by noting it provides human-readable detail for one builder while buildx_list returns machine-parsed JSON for all builders. This leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with buildx_list for JSON output, effectively guiding the agent on when to use which tool. It also explains the bootstrap parameter's role ('Boot the builder if it isn't already running'). This provides clear context for selecting the tool and using its options.
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 discloses critical behavioral traits beyond the annotations: it always passes `--force` because MCP lacks an interactive prompt, directly addressing the destructive nature. It also explains the return format. This adds significant value beyond the destructiveHint and idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: a one-line purpose, a prominent destructive warning, then a clean parameter list. Every sentence adds essential information, with no fluff or repetition of schema defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects, no output schema), the description is remarkably complete. It covers the return structure, warns about forced behavior, provides parameter examples, and mentions the companion tool buildx_du. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), but the description compensates fully by documenting every parameter with concise explanations and concrete examples (e.g., filters as JSON, space values as strings like '10GB'). This gives the agent the semantic context needed to populate parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove BuildKit cache entries.' This clearly states the tool's purpose with a specific verb (Remove), a specific resource (BuildKit cache entries), and differentiates it from sibling tools like buildx_du (which inventories disk usage) and buildx_remove (which removes builders).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage guideline by recommending 'Pair with buildx_du first to inventory what would be removed.' This tells the agent when to use this tool relative to a sibling. However, it does not explicitly discuss when NOT to use it or mention alternatives, so it stops short of a 5.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable failure semantics: 'Does not raise on a non-zero CLI exit: on a failed render config may be None — inspect raw.stderr.' This goes beyond the structured annotations by explaining error behavior and return state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a focused purpose sentence, usage guidance, failure behavior, then an args list and return specification. Every section earns its place and there is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description fully specifies the return dict shape: config as str/dict/None, raw as CliResult dict, and the parsing behavior for format='json'. Combined with parameter coverage and annotations, this is sufficiently complete for an agent to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 compensates fully with concise one-liners for all six parameters, including useful details like project_dir default/copy behavior, files repeatability, services_only mapping to --services, and format behavior. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Render the canonical compose configuration after merges, profiles, and variable substitution.' This clearly distinguishes compose_config as a read-oriented rendering/validation tool, not an operational Compose action like compose_up or compose_down.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance: 'Use it to validate compose files and see exactly what the CLI will run before compose_up.' This gives a concrete when-to-use scenario, though it does not explicitly mention when not to use it or name alternatives to exclude.
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?
With annotations only providing readOnlyHint=false and destructiveHint=false, the description carries the burden of behavioral detail. It states that containers are not started, explains the project_dir copying behavior for remote hosts, and mentions ignore_pull_failures semantics and timeout default. It does not contradict annotations and adds useful context, though it could elaborate on failure modes beyond the return dict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, then usage guidance, then a parameter list, then return value. Every sentence adds value—no filler. It is longer than average, but the added length is justified by the density of useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description includes the return dict format, which covers expected results. It also provides parameter details, alternatives, and prerequisites. For a tool with 6 parameters and no schema coverage, this description is remarkably complete and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the 6 parameters. It does so: project_dir, files, project_name, services, ignore_pull_failures, and timeout_seconds each get a clear, schema-enriching explanation. This more than compensates for the lack of schema-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Pre-fetch images for a compose project's services without starting them.' This clearly states the verb, resource, and scope, and distinguishes it from siblings like compose_up and image_pull by emphasizing the separation of pulling from startup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('stage images before an outage window', 'refresh cached images before compose_up', 'verify images are accessible without starting containers') and directly contrasts with compose_up --pull always, telling the agent when to prefer this tool. It also notes the prerequisite for registry-authenticated pulls (system_login).
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=false and destructiveHint=false, but the description adds value by specifying exactly what happens: containers are not removed, and state survives so compose_start can restore them. It also notes that stop_timeout_seconds is passed as `--timeout`, disclosing a key behavior. It does not mention side effects like process termination inside containers, but that is implied by 'stop services' and the non-destructive guarantee.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and the key differentiator from compose_down. The args section is structured and includes defaults/explanations. Every sentence provides useful information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the six parameters, zero schema coverage, and no output schema, the description provides everything needed to invoke the tool: it lists all parameters, their defaults, and the return dict shape (returncode, stdout, stderr, truncated). This is sufficient for an agent to select and call compose_stop correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully carries parameter semantics. It explains all six parameters: project_dir (default and host copying if no local plugin), files (repeatable -f), project_name (override), services (default all), stop_timeout_seconds (grace period), and timeout_seconds (subprocess default 300s). This is complete and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Stop services in a compose project without removing their containers.' This precisely distinguishes compose_stop from its siblings, particularly compose_down and compose_start. The scope is clear: it stops services but preserves containers/networks/volumes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts with compose_down: 'Unlike compose_down, containers/networks/volumes survive — use compose_start to bring them back.' This tells the agent when to choose this tool (when persistence of infrastructure is desired) and points to the sibling for the reverse operation. The parameter defaults and the fact that services defaults to 'all' further clarify usage context.
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 valuable behavioral details beyond the readOnlyHint and destructiveHint annotations: output is ps-style text (not JSON) read from stdout, and the tool does not raise on non-zero CLI exit (inspect returncode/stderr). This fully discloses the tool's observable behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: main purpose first, then output format, error behavior, parameter list, and return value. Every sentence contributes necessary information without restating schema defaults or annotations. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with 4 parameters and no output schema, the description covers purpose, output format, error handling, parameter semantics, and return structure. It is self-sufficient for an agent to select and invoke the tool correctly, and it even mentions the alternative 'container_top'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by listing all four parameters with readable explanations. It adds meaningful semantics such as 'project_dir' being copied to the target host if no local plugin, and 'files' being repeatable via '-f', which are not evident from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb+resource: 'Show the running processes of a compose project's containers.' It clearly distinguishes from related tools by noting the per-container equivalent is 'container_top' and by emphasizing compose project scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context for use (compose project containers) and explicitly names 'container_top' as the per-container alternative. However, it does not explicitly contrast with the sibling 'compose_ps' or state clear when-not-to-use conditions, so it falls slightly short of full guidance.
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 indicate this is not read-only and not destructive, and the description aligns by stating it creates a container. It adds key behavioral context: the container is not started, and the return value is 'the created container's attrs (not yet running).' It does not describe lifecycle persistence or cleanup implications, but the annotation coverage plus explicit creation/not-running behavior make this sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a usage paragraph, an args section, and a returns line. Every sentence adds value—examples and alternatives are concrete rather than filler. Though slightly long, the density of actionable information justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema, the description covers purpose, usage context, alternatives, parameter details, common kwargs, and return type. It also explains when not to use it (common case should use container_run) and how to discover additional options. This is complete enough for an agent to invoke correctly without prior knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by documenting every parameter: image with example, command with allowed types (string or list), and extra_kwargs with common keys, value formats, and examples (name, environment, ports, volumes, labels). It even warns against guessing unknown keys and points to docs_lookup, which is excellent semantical guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a container from an image without starting it.' It explicitly distinguishes this from container_run (create-and-start immediately) and container_start (starting an existing container), making the resource and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: configure a container with extra_kwargs before first start, or want separate observable steps. It names alternatives directly: use container_run for create-then-start-immediately and container_start to start the created container. It also tells users to call docs_lookup for unsupported extra_kwargs, preventing guesswork.
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 behavior beyond annotations: changes take effect immediately on Linux (cgroups), not all fields are updatable on every platform, and the container is not recreated. Annotations only indicate readOnlyHint=false and destructiveHint=false; the description enriches this with timing and platform constraints. A minor gap is lack of mention of error cases or permissions, but it earns a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a purpose sentence, a caveat paragraph, a detailed list of keys, and an args/returns block. Every sentence adds value, and formatting with code spans and line breaks improves scannability. It is long but appropriately so for a tool with a complex `updates` object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the minimal schema (no descriptions, no output schema) and basic annotations, the description provides essential context: valid keys, platform behavior, return value type, and when to use alternative tools. It covers the tool's core semantics thoroughly, leaving little ambiguity for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no property descriptions), so the description carries the full burden. It lists common `updates` keys with concrete examples (e.g., mem_limit, cpu_shares, restart_policy) and explains the `restart_policy` dict structure. The args section also clarifies both parameters, fully compensating for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Update resource limits on a container without recreating it', using a specific verb ('update'), a clear resource ('container'), and a meaningful qualifier ('resource limits', 'without recreating it'). This distinguishes it from sibling tools like container_rename, container_restart, and container_remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'To change image, env, or volumes the container must be recreated (`container_remove` + `container_run`)' names specific alternatives. It also notes platform differences for updatable fields, helping the agent choose when this tool is appropriate.
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?
Annotations only declare readOnlyHint=true and destructiveHint=false. The description goes far beyond this by explaining the HEAD request mechanism, that it costs no pull budget, how credentials affect metering, the environment variable fallback, and that unlimited plans return no headers (reported as 'unlimited': true). This is rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and uses each sentence to convey essential behavioral details. The args and returns sections are clearly formatted and concise, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description lists the exact return keys, explains edge cases (unlimited plans, missing headers), and covers authentication behavior. Given the tool's moderate complexity, this is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only parameter names and defaults, with zero descriptions. The description compensates fully by explaining that username/password are optional, override the corresponding environment variables, and that passwords/tokens are accepted. This adds critical semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise statement: 'Report the caller's remaining Docker Hub pull-rate-limit budget.' This names a specific verb ('report'), a specific resource (pull-rate-limit budget), and immediately distinguishes this tool from sibling hub tools like hub_tags and hub_repo_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call it before a large compose_pull / image_pull to avoid hitting the cap mid-deploy,' giving a clear when-to-use scenario. It does not provide explicit when-not-to-use guidance or name alternatives, but the context is unmistakable.
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 useful behavioral context beyond the annotations: in-band bytes are base64-encoded, `from_file` streams directly to the daemon, `~` is expanded, and file access is under the server user's permissions. It does not explicitly describe the local image-store mutation semantics, but annotations already mark readOnlyHint=false and destructiveHint=false, and loading implies writing to the daemon's image store.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough yet every sentence earns its place. It starts with the core purpose, follows with clear usage guidance and alternatives, then covers parameter mechanics and return shape in a readable format. No filler or tautology is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description specifies the return type as a list of full inspect payloads per loaded image. It also covers the main usage distinctions, parameter options, file path semantics, and transfer trade-offs, making it complete enough for reliable tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no parameter descriptions, but the tool description fully compensates by explaining `data` as tarball contents in-band, `from_file` as a server-host path from a `docker save`/`image_save` bundle, and the mutual exclusivity constraint. It also adds practical context about streaming and base64 encoding that is absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Load an image from a tarball produced by `image_save`'. It also clearly distinguishes itself from `image_pull` and `image_import`, which are the closest sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool versus alternatives: registry images should use `image_pull`, flat rootfs archives should use `image_import`. It also recommends `from_file` for anything but small images and clarifies the 'exactly one of' constraint, giving an agent actionable selection criteria.
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?
Annotations already indicate destructive=true, but the description adds essential behavioral context: default removes only dangling images, filters can expand to all unused images, valid filter keys are enumerated, and return information includes space reclaimed. This goes well beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a focused paragraph on behavior and filters, and a concise args/returns breakdown. Each sentence contributes necessary information for a destructive prune operation without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though no output schema exists, the description states the return dict structure. It covers purpose, filter usage, default behavior, and references system_df. For a one-parameter tool with strong annotations, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for the `filters` object, but the description fully compensates by explaining valid filter keys (`dangling`, `until`, `label`) with value formats and the effect of omitting filters. This is high-value semantic information that is otherwise absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove unused local images to reclaim disk space.' It distinguishes from sibling prune tools by explicitly targeting 'local images' and explains the default dangling-only scope, which differentiates it from image_remove and other prune variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: recommends 'Use system_df first to see how much space is reclaimable' and explains how to choose between dangling-only and all-unused images using filters. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit 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 indicate readOnlyHint=false and destructiveHint=false, so the mutation is already known. The description adds valuable context about credential requirements for private repos and the return format (dict or list), going beyond the annotations. It does not go into side effects like overwriting existing images, but for this tool the provided context is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening statement, a credential note, alternatives, parameter list, and returns. Every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters and an output schema, the description covers purpose, usage conditions, alternatives, parameter semantics, and return values. It provides all necessary operational context without requiring additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates by explaining each parameter (repository, tag, all_tags, platform) and the interaction between tag and all_tags (tag is ignored when all_tags=True). The returns section also clarifies the output shape.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Pull' and the resource 'an image from a registry to the daemon's local store', which is specific and distinguishes it from sibling tools like image_load (tarballs) and registry_manifest (remote inspection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that private repositories need credentials via system_login or docker login, and explicitly recommends image_load for tarballs and registry_manifest/image_registry_data for remote inspection, providing clear when-to-use and alternatives.
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?
Annotations already indicate read-only and non-destructive behavior, and the description adds substantial context beyond that: the tool does not pull the image, it relies on the daemon's cached credentials, and it warns that `auth_config` may be logged verbatim. This disclosure of internal mechanism and security implications exceeds what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with separate paragraphs for purpose, usage, security, and argument documentation. Every sentence adds value, but the multi-paragraph format is slightly more verbose than necessary. The front-loaded first sentence conveys the core purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, read-only, no output schema), the description is complete: it explains the operation, the return dict structure, the dependency on the daemon, the alternative tool, and security considerations. No critical aspects are missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates with brief but meaningful explanations: 'repository - Image reference' and 'auth_config - Optional registry authentication config.' It also adds a security note that clarifies how to treat auth_config. While the parameters are not deeply detailed, the description provides adequate meaning for the agent to use them correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get registry data for an image without pulling it, via the daemon's distribution endpoint.' It identifies the specific resource (image registry data), the operation (get), and the method (daemon distribution endpoint). It also distinguishes itself from sibling tools like `registry_manifest` by specifying the daemon-dependent approach.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage context and an alternative: 'For direct registry access without a daemon use `registry_manifest`.' It also gives security guidance on when to use `auth_config` and recommends leaving it unset in favor of `docker login`, which helps the agent decide how to invoke the tool.
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?
Beyond the annotations (destructiveHint=true), the description details failure modes (multiple tags, stopped containers, running containers always block), force behavior, and noprune side-effects. This is extensive behavioral context that helps prevent misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-sentence purpose, followed by specific behavioral nuances, then an args block. Every sentence adds value, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive image removal tool, the description covers all necessary context: parameters, failure conditions, side-effects, and return value. Despite no output schema details, the return type is stated. The description is complete for safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully compensates by explaining each parameter: id_or_name, force, and noprune. It adds meaning beyond names, including the effect of force and noprune, and even states the return type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a local image by name or id' with a specific verb and resource. It distinguishes from siblings like image_prune and image_tag by focusing on removing a single named image and addressing tagging/container references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when removal succeeds/fails, including prerequisites like untagging with image_tag when multiple tags exist. It doesn't explicitly compare against alternative removal tools like image_prune, but the usage conditions are well explained.
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 and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: the registry scope (Docker Hub only), the return format (list of dicts with specific keys), and the default limit behavior. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then exclusions/alternatives, then parameter details, then return type. Every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description covers everything needed: what it does, scope, alternative, parameter semantics, and return shape. There are no gaps that would confuse an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions (0% coverage), but the description fully documents both parameters: `term` is explained with examples, and `limit` is explained with its Docker Hub default of 25. This adds meaning that the schema lacks, making it easy for an agent to know exactly what to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb+resource: 'Search Docker Hub for public images matching a term.' It clearly distinguishes from sibling tools by explicitly excluding other registries and referencing `registry_tags` as the alternative for listing tags from any OCI registry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use and when-not-to-use guidance: 'Searches Docker Hub only — not GHCR, ECR, or other registries. For listing tags on a specific image from any OCI registry use `registry_tags` instead.' This clearly directs the agent to the proper alternative.
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?
Beyond the minimal annotations (readOnlyHint=false, destructiveHint=false), the description adds notable behavioral context: creation attaches nothing, provenance labels are stamped, and check_duplicate behavior is noted. It doesn't mention permissions or error cases but covers key traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a one-line summary, key behavioral notes, and a clear arg list. Every sentence provides value, and the length is appropriate for the parameter count. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high complexity (11 params, nested objects, no output schema), the description covers usage, parameter meanings, return format (dict with attrs), and ties to related tools. It is sufficiently complete for an agent to invoke correctly without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description fully compensates by explaining each of the 11 parameters, including IPAM shape, driver defaults, and special flags like ingress and attachable. This adds significant meaning beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a network' with the resource and action. It differentiates from sibling tools like network_connect and network_disconnect by focusing on creation. The addition of daemon default driver and overlay usage clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (for swarm-wide networks use overlay), how to connect containers afterward via network_connect or container_run, and how to find created networks via network_list(managed_only=True). This distinguishes it from alternatives and gives clear usage context.
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?
Beyond the readOnlyHint annotation, the description discloses performance costs ('one extra daemon call per network'), filter behavior (valid keys and shorthand semantics), and the managed_only label filtering. It also specifies return format (summary vs full attrs), adding substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then methodically covers filters and parameters. Each sentence delivers meaningful detail without redundancy, and the args/returns structure improves scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return format, all parameter semantics, performance trade-offs, and filter syntax, which is comprehensive for a read-only list tool with no output schema. It leaves no obvious gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully documents all five parameters. It explains exact name/id filtering, valid filter keys (driver, label, type), the combination of names/ids with filters, and the managed_only label behavior, completely compensating for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List networks,' a clear verb+resource statement that distinguishes it from other network tools. It further clarifies that greedy mode adds the connected-containers detail that network_inspect returns, making its role distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use greedy versus default mode ('leave it False for a fast summary list') and contrasts with network_inspect. It does not explicitly name alternative tools like network_create or network_remove, but the context is sufficient for the primary list-vs-inspect decision.
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 and destructiveHint=false, and the description adds useful context: it is a fleet view, returns full node documents with specific fields, and requires a swarm manager. No contradiction with annotations. It does not mention pagination or rate limits, but with strong annotations and return details, this is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action 'List swarm nodes'. The subsequent sentences add essential context, usage notes, and return format, all without redundancy. The args/returns structure is efficiently included without breaking flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is complete: it explains the return format (list of full node documents with specific fields), the runtime requirement (swarm manager), and provides pointers to alternatives for deeper inspection. No additional detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema merely defines 'filters' as an object with no description, but the description compensates by explicitly listing 'Filter by attributes (id, name, membership, role)'. This gives the agent concrete guidance on what to pass for the parameter, which is essential given 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List swarm nodes' with a specific verb and resource. It further distinguishes itself from siblings by noting 'drill into one node with node_inspect, or read the docker://nodes resource for a computed summary', making it explicit that this tool is for the fleet-level view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage guidance: 'Must run against a swarm manager' sets the prerequisite, and it explicitly names alternatives (node_inspect for single node, docker://nodes for summary), helping the agent decide when to choose this tool over others.
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 only include readOnlyHint=false and destructiveHint=false, which are minimal. The description compensates by revealing that the plugin must be disabled before reconfiguring and that the operation returns a boolean after configuration. It also warns that option keys must match the plugin's declared env keys. However, it does not mention what happens if the plugin is active (e.g., error) or whether unlisted settings are overridden, leaving some behavioral nuance undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written with no filler. It leads with a one-sentence purpose, follows with actionable instructions and an example, then lists args/returns in a clear format. Every sentence earns its place; the structure is easy to scan and parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple schema, the description covers the full workflow: how to discover valid keys, how to construct options, the disable/configure/enable sequence, and the return value. It even includes an example. Given the tool's modest complexity and the availability of an output schema, the description is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only names and types with zero description coverage. The description adds rich semantic detail: name is exemplified ('vieux/sshfs:latest'), options are explained as 'Key/value settings to apply, matching the plugin's declared env keys', and a concrete dict example is given. It also tells the agent where to find valid keys (Settings.Env via plugin_inspect), fully compensating for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Set runtime configuration options on an installed plugin.' This clearly distinguishes it from sibling tools like plugin_inspect (viewing config) and plugin_disable/enable (lifecycle operations). The phrase 'runtime configuration options' conveys the exact scope of the tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use plugin_inspect first to see which keys the plugin exposes under Settings.Env' and 'The plugin must be disabled before reconfiguring — call plugin_disable first if it is currently active, then plugin_enable afterwards.' This tells the agent both the prerequisite workflow and how to alternate with related tools, leaving no ambiguity about when/how to invoke.
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 discloses behavioral implications beyond the annotations: enabling causes Docker to route API calls through the plugin, and timeout_seconds controls the health wait. It does not, however, mention potential side effects such as service disruption or how enabling affects existing plugin state, but the core behavior is clearly conveyed. Annotations already indicate mutation (readOnlyHint: false), so the description adds useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise opening definition, followed by relevant usage context and configuration advice, then a clear args/returns section. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters, an output schema, and annotation context, the description is complete. It explains what the tool does, when to use it, how parameters behave, and even covers the related configuration workflow. No critical information seems missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explicitly defining both parameters: 'name - The plugin name to enable' and 'timeout_seconds - Seconds to wait for the plugin to become healthy (0 = no timeout)'. This adds meaning far beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Activate') and resource ('an installed plugin'), and explains the functional outcome ('so Docker routes relevant API calls through it'). It distinguishes itself from sibling tools by focusing on enabling a disabled plugin, while siblings handle install, disable, configure, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use: 'a plugin that is currently disabled — either freshly installed or previously disabled via plugin_disable'. It also provides a key prerequisite: if the plugin exposes configuration, call plugin_configure while disabled before enabling. This effectively tells the agent the recommended order of operations relative to sibling tools.
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?
While annotations already indicate readOnlyHint=false and destructiveHint=false, the description adds valuable behavioral context: the plugin must be disabled first, and existing settings/volumes persist across the upgrade. This goes beyond the annotation basics, though it could also mention failure modes or permission requirements to reach a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a usage paragraph covering prerequisites and persistence, then clear args and returns sections. Every sentence adds value, with no filler or redundant repetition of schema data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (prerequisite disable/enable, remote reference semantics, persistence guarantee), the description covers all needed aspects: workflow, parameter behavior, return type, and persistence. It is complete enough for an agent to invoke the tool correctly, and the return schema is simple (bool) requiring no extra explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has no descriptions (0% coverage), the description fully compensates by explaining both parameters: `name` as the plugin to upgrade and `remote` with a concrete example ('vieux/sshfs:next') and default behavior. It also clarifies the return value, making the parameter and output semantics complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Upgrade an installed plugin to a newer version,' which clearly states a specific action (upgrade), target (installed plugin), and outcome (newer version). This distinguishes it from sibling tools like plugin_install, plugin_disable, and plugin_enable, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call plugin_disable before, and plugin_enable after, the upgrade. It also explains when to use the `remote` parameter versus omitting it (to re-pull the same reference). This is clear, actionable usage guidance with no ambiguity about the intended workflow.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable non-obvious behavior: it requires docker login to be useful, does not raise on non-zero CLI exit (except when scout plugin missing), and outputs plain text only. It also explicitly points to inspecting raw.stderr for errors, which is beyond annotation info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately lengthy but well-organized: purpose statement, context, output/error behavior, and args list. Each section serves a distinct purpose and is not redundant. The args section is necessary due to 0% schema coverage. It could be tightened slightly (e.g., merging some sentences) but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema, non-trivial error handling), the description covers all essential aspects: purpose, dependencies (login), output format, error semantics, parameters, and return value structure. It even mentions the relationship to scout_cves. This is sufficient for an agent to correctly invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must define parameters. It lists all 5 args with brief but meaningful descriptions: only_refresh and only_update explain the distinction between same major/minor and newer, tag clarifies pattern matching, platform clarifies target, and image is defined. Although not exhaustive, it compensates for the missing schema descriptions adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Suggest base-image upgrades for an image.' It names the specific resource (base-image upgrades) and verb (suggest). It also distinguishes from siblings by noting it is 'The natural follow-up to scout_cves,' which shows unique positioning among the scout_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use this tool: 'The natural follow-up to scout_cves when the fix is a newer base image.' It also notes prerequisites (docker login) and mentions the output limitation (plain text only). This gives clear guidance for selection among alternatives.
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?
Even though annotations already declare readOnlyHint=true, the description adds valuable context: results never include secret data, only metadata, and a swarm manager is required. This goes beyond the annotations and clarifies privacy and prerequisite behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and includes necessary details (filter keys, args, returns) without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description covers the operation, prerequisites, safety characteristics, filter options, and return type. No output schema exists, but the return format is described. It is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'filters' as an object with no description, but the description explains its purpose ('Narrow the list; omit to return every secret') and lists valid filter keys. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List swarm secrets' metadata' with a specific verb and resource, and distinguishes it from secret_inspect by emphasizing metadata-only results. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context by mentioning 'requires a swarm manager' and compares behavior with secret_inspect, but does not explicitly state when to use this tool vs alternatives or when not to use it. The guidance is clear but not fully explicit.
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 and destructiveHint=false. The description adds useful behavioral context: the requirement to run against a swarm manager, and that the response includes desired-state spec, rollout status, and UpdateStatus during rolling updates. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, then prerequisites and alternatives, then labeled args and returns. Every sentence adds value; no fluff or redundancy beyond a minor mention of desired-state spec in both the intro and returns, which is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return format (full service document with key fields). It covers prerequisites, alternatives, parameters, and behavioral nuances, making it complete for an inspect tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does: 'id_or_name - The service id or name' and 'insert_defaults - Merge default values into the output', adding meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Get a swarm service by id or name,' using a specific verb and resource. It distinguishes from service_ps by clarifying it returns desired-state spec and rollout status, not running tasks, and points to alternatives for that purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Must run against a swarm manager' and provides clear alternative guidance: use `service_ps` or the `service-tasks://` resource for running tasks. This is explicit when-to-use and alternatives guidance.
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?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), it reveals critical behaviors: never raises on timeout, always returns met/timed_out, uses specific task-counting logic rather than unconfirmed daemon field, and returns met=false for never-updated services. This is rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than typical but every sentence carries information: purpose, contract, mode-specific behavior, parameter semantics, and return keys. It is well-structured with a clear heading and list, front-loading the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description lists the return dict keys. It also covers both modes, timeout behavior, and parameter interactions, making it complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains every parameter in detail: id_or_name, until with enum values, replicas as an override, timeout_seconds with default, and poll_interval with capping behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Block until a swarm service's tasks converge, or a rolling update finishes.' This clearly distinguishes it from sibling wait tools like container_wait and compose_wait by naming 'swarm service' as the target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed context for both modes ('running' vs 'update-converged') and explains when each terminates, including the edge case for never-updated services. However, it does not explicitly state when to choose this over sibling wait tools, relying on the resource specificity.
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?
Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds substantial behavioral details beyond that: tears down services/networks/secrets, does not raise on non-zero CLI exit (instructs to inspect returncode/stderr), and explains the detach default behavior. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately detailed and front-loaded: main purpose, destructive warning, behavioral notes, then structured parameter descriptions. Every sentence adds value, with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given its destructive nature and the lack of an output schema, the description is complete. It specifies the return dict format, exit-code behavior, teardown scope, parameter behaviors, and default detach behavior, equipping the agent to use it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 provides meaningful explanations for all three parameters: names (required, one or more), detach (immediate vs await teardown), and timeout_seconds (default 300s). This fully compensates for the schema's bare structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove one or more stacks from the swarm' and explicitly details the scope (services, networks, secrets). It distinguishes itself from siblings by referencing stack_deploy as the reverse and compose_down as the swarm analogue, making its unique role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong contextual guidance: it is destructive, reverses stack_deploy, parallels compose_down, and defaults to detach=True. It does not explicitly list when-not-to-use cases, but the clear inverse relationship to stack_deploy and the destructive nature imply appropriate usage contexts.
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?
Beyond the destructiveHint annotation, the description discloses key behavioral traits: service tasks are rescheduled, leaving can break raft quorum, managers are refused without force, and the departed node remains 'down' until a manager removes it. This is rich, non-obvious context that helps the agent anticipate consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficiently structured: a one-sentence purpose, a two-sentence behavioral explanation, and a clear args/returns block. Every sentence adds value without redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool with annotations, the description covers all essential aspects: what it does, when force is needed, what side effects occur, what the parameter means, and what the return value is. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines a boolean 'force' with a default. The description explains the parameter's meaning ('Force leave even if node is a manager') and also specifies the return type and value ('True after leaving'). This fully compensates for the lack of schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action 'Leave the current swarm' with a specific verb and resource, clearly distinguishing it from sibling swarm tools like swarm_init, swarm_join, and swarm_update. It also adds behavioral context that reinforces its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: managers must set force=True to leave, and the node will linger as 'down' until node_remove is run. While no explicit alternatives are mentioned, the unique nature of the action makes this unnecessary. The force guidance is a practical rule for when and how to use the tool.
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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return payload structure (Name, Driver, Mountpoint, CreatedAt, Labels, Options, Scope) and the lack of IDs. It doesn't cover error behavior, but for a simple read-only inspect tool, the additional context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement, a usage note, and properly labeled sections for arguments and return values. Every sentence adds value: the usage note provides context, and the args/returns section succinctly documents the API. It is concise without being terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description lists the expected return keys, which fully informs the agent about the result structure. It also includes usage context for the volume lifecycle. For a single-parameter, read-only tool with strong annotations, this description is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage (the parameter 'name' is just a string with no explanation). The description compensates fully by including 'args: name - The volume name (volumes have no ids)', which not only clarifies the parameter's purpose but also explains why there is no id. This is a complete semantic addition for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get a volume's full inspect payload by name.' This is a specific verb+resource combination that distinguishes it from volume_list (which lists volumes) and other inspect tools (which inspect different resource types). The additional context about addressing volumes by name without ids further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use it after volume_list' and provides concrete examples such as 'before a backup or volume_remove.' It also clarifies the addressing scheme ('volumes have no separate id'), which helps the agent understand prerequisites and avoid common mistakes. This is explicit usage guidance with context.
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 mark this as destructive and idempotent. The description adds useful nuance about what counts as 'unused' (stopped containers still protect a volume), the default anonymous-only behavior, and the return payload. It doesn't cover permission requirements or confirmation behavior, but the annotations plus added context are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then elaborates on edge cases, filter keys, and pre-conditions in a structured way. The args/returns section at the end is clearly labeled. Every sentence provides actionable information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explicitly states the return dict shape (VolumesDeleted and SpaceReclaimed). It covers usage context, default behavior, filter semantics, and sibling tool coordination (volume_list, container_prune), making it self-sufficient for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the only parameter (filters) has no schema description. The description fully compensates by explaining that filters narrow which unused volumes to remove, omitting removes all anonymous ones, and listing valid filter keys (label, all) with their syntax and semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Remove volumes not referenced by any container, running or stopped." It clearly scopes the operation (unused volumes only) and distinguishes it from sibling tools like volume_remove and container_prune.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use it versus alternatives: volumes used by stopped containers survive, so remove the container first or use container_prune first. It also advises using volume_list to see what exists and explains filter key usage, including the all key's default behavior.
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?
Adds behavioral context beyond annotations: raises RuntimeError on CLI failure, parses from JSON format, and drops a truncated final record. This complements the readOnlyHint/destructiveHint annotations with factual execution details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action. It uses two sentences plus a returns bullet, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (0 params, list operation), the description covers all essential aspects: return type, error behavior, truncation handling, and relationship to sibling tools. Annotations provide safety profile, completing the picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so there are no parameter semantics to clarify. The description does explain the return format and handling of truncation, but that's not parameter-related. Baseline 4 for 0 params is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'List builder instances,' a specific verb+resource statement. It also distinguishes from siblings by naming buildx_inspect for one builder's human-readable detail and buildx_use for switching the default.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (machine-parsed view of every builder) and points to alternatives (buildx_inspect for detail, buildx_use to switch default), giving clear when-to-use and when-not-to-use guidance.
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?
Annotations already state readOnlyHint=true and destructiveHint=false, but the description adds valuable context: swarm manager requirement, post-creation readability, and base64 encoding of Spec.Data. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence. Every subsequent sentence adds essential context: preconditions, comparison to secrets, usage guidance, and return format. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, no-output-schema tool, the description covers prerequisites, usage, return value structure, and behavioral nuance. Fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full weight. It defines id_or_name as accepting 'id or name' and documents the return dict's structure (ID, CreatedAt, UpdatedAt, Spec fields). Adds clear meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a swarm config's full inspect payload by id or name', which is a specific verb+resource+scope. It also distinguishes from config_list by noting 'use this to read one config's contents and metadata'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Requires a swarm manager' and contrasts with secrets: 'Unlike a secret, a config's payload IS readable after creation'. It also directs users to config_list for enumeration, providing clear when-to-use vs alternatives.
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?
Annotations only indicate non-read-only and non-destructive, but the description reveals key behavioral traits: the freezer cgroup mechanism, invisibility of the suspension to processes, resource retention, zero CPU usage, and the interaction with exec. This goes far beyond the minimal annotations and provides deep insight into what happens when pausing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose sentence, a brief behavioral explanation, and an args/returns section. Every sentence adds value without bloat, and the structure makes key information easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter state-changing operation, the description covers the core behavior, resource impact, recovery path, and a critical limitation (exec fails). It also specifies the return value (inspect payload with State.Paused). This is a complete picture for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by defining the sole parameter: 'id_or_name - The container id or name'. This adds meaning beyond the raw string type, clarifying that either a container ID or name can be provided. While simple, it fully covers the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Suspend all processes in a container using the kernel freezer cgroup.' It uses a specific verb (suspend), resource (container), and mechanism (freezer cgroup), and distinguishes it from SIGSTOP and sibling tools like container_stop/container_kill. The purpose is unambiguous and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use this tool by contrasting with SIGSTOP (suspension cannot be observed/intercepted) and notes that a paused container keeps resources but uses no CPU. It also provides clear direction to resume with container_unpause and warns that container_exec will fail until unpaused. This gives explicit context and related-tool alternatives.
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?
Annotations only declare readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavior: it resumes processes, notes that processes continue from where they were frozen, and explains the return value (State.Paused becomes false). This goes well beyond the annotations and gives the agent a clear model of the operation's effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each serving a distinct purpose: purpose, usage guidance, and parameter/return details. No filler or repetition, and it is front-loaded with the most important information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers all essential aspects: what it does, when to use it, what happens in the failure case, and what the return value contains. There is no missing information that would cause an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and a parameter named `id_or_name` with no description. The description compensates with 'args: id_or_name - The container id or name', which clarifies the parameter's purpose. However, this is a minimal rephrasing of the parameter name and could add more detail (e.g., accepts ID or name, not both). Still, it is enough to make the parameter understandable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Resume all processes in a paused container', clearly stating the tool's function. It further distinguishes itself from the sibling tool `container_pause` by calling itself the reverse, and from `container_start` by specifying the paused vs stopped distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (only on a paused container), when it fails (if merely stopped), and directs the user to the alternative (`container_start` for stopped containers). This is exactly the kind of clear usage guidance expected.
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?
Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses that the server uses the startup-resolved DOCKER_HOST/current-context, so changing contexts only affects subprocess-based tools, not the docker-py SDK client. It also mentions RuntimeError on CLI failure. These add meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, then provides essential context about CLI behavior, sibling tool guidance, error handling, and return format. Each sentence adds value, and the structure is logical and brief enough for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description specifies the return value ('list - One dict per context with at least name, description, dockerEndpoint, and current'). It also covers error behavior, context semantics, and usage guidance, making it fully complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty. Per the rubric, a baseline of 4 applies when there are no params. The description doesn't need to explain parameters, and it correctly omits any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function as 'List Docker CLI contexts known to the host running this MCP server.' It distinguishes itself from siblings by explicitly naming context_inspect (full config of one context) and context_use (switching), making the tool's scope and relationship to alternatives unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is provided: 'Use context_inspect for one context's full config and context_use to switch.' It also explains the server's context resolution behavior, helping the agent understand when the tool is relevant and what side effects might exist.
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?
Annotations already indicate readOnlyHint and destructiveHint, but the description adds substantial behavior: always registered regardless of DOCKER_MCP_SERVER_DISABLE, per-section refusal if the domain is disabled, the listing-vs-fetch behavior, and the return type (JSON index or raw HTML/Markdown). This is rich behavioral context beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but each sentence earns its place: purpose, registration behavior, parameter behavior, use cases, and return format. It is front-loaded with the core purpose and structured logically, though it could be slightly tightened without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and an output schema, the description is comprehensive. It covers what the tool does, when to use it, edge cases (disabled domains), and return formats, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only has 'section' with a default null and no description (0% schema coverage), so the description must compensate. It fully explains the parameter: 'section - Section name (from a no-argument call's index); omit to list all sections instead,' and also describes the return values for both cases, making the semantics clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Look up' with the resource 'Docker SDK/CLI/registry reference documentation by section,' clearly distinguishing it from all sibling tools, which are operational commands. It also explains it's a mirror of docker-docs:// resources, adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'Most useful before constructing an extra_kwargs-style passthrough dict... or before writing Compose/Dockerfile/buildx bake-file syntax, which no tool generates.' It also notes that it serves as an alternative for clients that can't read MCP resources, and explains when sections refuse, giving clear exclusions.
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 surfaces the non-obvious, security-relevant fact that `dockerfile` can read arbitrary host files when given an absolute path or `..` traversal — critical risk disclosure that no annotation or schema field could convey. Also clearly documents the return value ('full inspect payload'), matching the expectation that a build is a write operation (consistent with readOnlyHint: false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The structure is logical: purpose → when to use → critical path-semantics warning → parameter glossary → return type. While long, the length is justified by the tool's 20 parameters and the description never rambles; each sentence adds information. The initial prose is front-loaded with the single most important 'when to use this vs. other' guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 20 parameters, zero required, no enums, and no output schema, this description is exceptionally complete. It covers the full use case matrix, explains edge cases (path traversal, host-file reads), documents every parameter with semantics beyond their names, and specifies the return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden of documenting all 20 parameters. It delivers: every param is explained with types ('dict of str→str'), concrete examples ('{"memory": 134217728}'), defaults ('default True'), and platform caveats (isolation on Windows). This is exactly the kind of compensation a rich description must provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
First sentence is precise: 'Build an image from a Dockerfile using the daemon's classic builder' — clear verb + resource + engine variant. Explicitly differentiates from the buildx_build sibling by naming the alternative for multi-platform/advanced features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('simple single-platform builds from a local context') and names the exact alternative ('prefer `buildx_build`') for other cases. Goes further by contrasting how the `dockerfile` parameter resolves in this tool vs. buildx_build's `--file`, giving agents critical context not discoverable from the schema.
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?
Adds substantial context beyond annotations: the destructive and immediate nature explicitly stated, API version requirements for each parameter, the `InvalidVersion` error case, and the transport flexibility. No contradictions with 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured, front-loading the action, then grouping context, alternatives, side effects, API notes, and parameter detail. While longer than the minimal necessary, every section earns its place; a slight trim in the `filters` enumeration would tighten it further.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers all the essential context: what the tool does, what resource it affects, when to prefer alternatives, what to run before, what side effects to expect, API version constraints, parameter details, and the return value shape. Complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates: explains `filters` with an example and comprehensive key list, `keep_storage` with byte example and the API v1.48 rename, and `all` with its behavior relative to unused records. This exceeds the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb + resource ('Delete the daemon's build cache to reclaim disk space') and immediately distinguishes it from `image_prune` and `buildx_prune`, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance, naming `buildx_prune` as the preferred alternative for non-default builders, recommending running both this and `image_prune`, and suggesting `system_df` or `buildx_du` for inventorying before pruning.
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?
Discloses the non-obvious replacement behavior: 'omitted keys are cleared' and the example about wiping role and labels. This goes beyond annotations (readOnlyHint=false, destructiveHint=false) by explaining the actual side effects and the necessity of using node_inspect first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured: purpose sentence, behavioral caveat, args/returns block. Each sentence adds value, though the args section could be more compact. It front-loads the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool, it covers the essential context: what the operation does, the non-merge semantics, how to prepare the value safely, and the return type. It also gives a concrete cautionary example, which is more than sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully defines both parameters: id_or_name as node id/name and spec as the complete new spec with the crucial caveat that omitted keys are cleared. This adds significant meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb+resource+fields: 'Replace a node's spec (availability, name, role, labels).' This clearly distinguishes it from node_inspect (read), node_remove (delete), and node_wait (status wait).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when and how to use: 'Replacement, not a merge' and advises fetching current spec via node_inspect, modifying, and resubmitting the whole dict. Also provides a concrete example of the pitfall (sending just Availability wipes role/labels), which serves as a clear guideline.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses crucial behavior: registry rejections surface as an 'error' key rather than raising, credentials come from system_login or ~/.docker/config.json, the plugin need not be enabled, a docker-py bug is worked around, and SSH daemons have a timeout limitation. This is rich, meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy and structured in paragraphs, but every sentence earns its place by covering purpose, context, error handling, edge cases, and parameters. It is front-loaded with the main purpose, and while it could be tightened, the detail is justified given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description details the return dict structure (name, progress, truncated, error), error semantics, credential requirements, and behavioral caveats. It provides complete context for using and debugging the tool in real-world scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining both parameters: 'name' format ([registry/]author/name:tag, :latest omitted, Docker Hub for bare author/name) and 'timeout_seconds' (max wall-clock seconds, default 300). The args section adds meaning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource statement, 'Push an installed plugin to its registry,' and clearly distinguishes this from plugin_install (pull) and image_push (no plugin equivalent of image_tag). It explicitly defines the tool's scope and relationship to sibling tools, 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool as the write-side counterpart to plugin_install and the publish step after plugin_create. It also notes the prerequisite that the name must already be registry-qualified, and contrasts with image_push by explaining there is no plugin rename step. This gives clear when-to-use and when-not-to-use guidance.
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?
Even though annotations include readOnlyHint=true and destructiveHint=false, the description adds significant behavioral context: output is plain text only with no output-format option, the result is always rendered text, and it discloses that non-zero CLI exits do not raise exceptions (except missing plugin) and suggests inspecting raw.stderr. This goes beyond annotations to describe error handling and output format nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loading the purpose in the first sentence. It uses short paragraphs and bullet-like structure for args and returns, making it scannable. Every sentence adds value—no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple interface (2 params, no output schema), the description is complete: it covers purpose, usage, output format, error behavior, and return structure. The agent can confidently invoke and interpret results without additional information. The return dict is explicitly described, compensating for the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 describes 'image' as 'Image reference' and 'platform' as 'Platform of the image to analyze, e.g. "linux/amd64"', which adds meaningful examples and clarity beyond the bare schema names. The description does not fully elaborate on image reference formats, but the provided context is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a compact summary of an image's CVE posture, with specific details on counts per severity and base-image status. It effectively distinguishes from siblings by naming scout_cves and scout_recommendations and describing what they do differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly positions the tool as the fastest triage step and provides clear guidance on when to use alternatives: scout_cves for machine-readable JSON and drill-down, scout_recommendations for upgrade suggestions. This is an explicit when-to-use and when-not-to-use pattern with named alternatives.
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 the readOnlyHint annotation: Xlucidity truncation behavior ('captured stdout is subject to MAX_CLI_OUTPUT_BYTES and may be truncated for big images'), error semantics ('Does not raise on a non-zero CLI exit (a missing scout plugin still raises)'), and instructions to inspect `raw.stderr`. These are precisely the non-obvious runtime behaviors an agent needs to know, with no contradiction to 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the purpose effectively and contains no fluff; every sentence earns its place. However, the middle paragraph is dense, cramming the truncation warning, the host fallback, and the exit-code behavior into a single run-on block that could be better structured with bullets for scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the 0% schema coverage, the description meaningfully covers all gaps: it documents the return dict, edge cases around truncation and exit codes, sibling distinctions, and all parameter semantics. It's complete even without explicitly explaining return values for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by documenting all three parameters. It expands all four enum values of `format` with their meanings, clarifies the `image` parameter as a reference, and explicitly documents the return structure including when `result` is a parsed dict vs raw text. This exceeds what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening line, 'Generate a Software Bill of Materials (SBOM) for an image,' uses a specific verb and resource, making the tool's function immediately clear. The description then goes further by distinguishing it from its sibling: 'Package inventory only — `scout_cves` adds vulnerability matching on top.' This explicit scope boundary and sibling differentiation is exactly what a score of 5 requires.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly defines when to use the tool ('Package inventory only') and points to the alternative (`scout_cves`) for vulnerability matching. It even provides a workaround for large SBOMs with a specific command suggestion ('run `docker scout sbom -o file.json …` on the host'), giving clear practical guidance beyond basic invocation.
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?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses key behavioral traits: never follows (avoids blocking), joins the stream into one string, caps at max_bytes with a ValueError, and aggregates across all tasks. These details are not present in annotations and are essential for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence contributes value. It front-loads the core purpose and then details caveats and parameter semantics in a structured list. Slight verbosity in the caveat paragraphs could be trimmed, but the structure is clear and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, output schema, safety concerns), the description is remarkably complete. It covers edge cases like unbounded output, OOM risks, and the difference from container_logs. The return type is specified as 'str - Decoded log output', making it self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description includes an args section that explains every parameter's meaning, defaults, and special values. For example, tail explains the default 200 and the literal 'all', max_bytes explains the ValueError abort, and since is defined as a Unix timestamp. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Get a bounded snapshot of a swarm service's logs (never follows)'. This clearly states what the tool does and its non-following behavior. It also distinguishes itself from siblings by mentioning 'container_logs reads a single container', providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: it warns against using 'tail="all"' due to context overflow, recommends using an integer or 'since' to constrain output, and contrasts with 'container_logs' for single-container logs. It also explains why 'follow' is not exposed. This goes well beyond implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description details what happens: 'Deletes the service definition and shuts down its tasks — no confirmation, no undo.' This adds crucial irreversible-behavior context. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-organized: purpose, prerequisites, effects, alternative, then args/returns. Every sentence delivers value with no redundancy, front-loading the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive service removal, the description covers prerequisites, behavior, alternatives, and return value. Paired with the destructiveHint annotation and output schema, this is complete for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining the sole parameter ('id_or_name - The service id or name') and the return value ('True after the service is removed'). While the parameter explanation is minimal, it clarifies the expected input and output, which is adequate for this simple tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Stop and remove a swarm service.' It distinguishes itself from siblings by naming service_scale as an alternative for non-destructive stopping, 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a prerequisite ('Requires a swarm manager') and explicitly provides an alternative usage scenario: 'To stop work but keep the definition, `service_scale` to 0 replicas.' This gives clear when-to-use vs. when-not-to-use guidance.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: it parses output via `--format '{{json .}}'` but abstracts that, states a prerequisite (swarm manager), explains error behavior (raises RuntimeError on CLI failure), and describes the return shape (list of dicts with name, services count, orchestrator).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—four sentences, each serving a distinct purpose: what it does, when to use it, error behavior, and return value. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with annotations and no output schema, the description covers all essential aspects: purpose, prerequisites, error handling, and return format. It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score is 4. The schema is empty and the description correctly avoids inventing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists stacks deployed to the swarm, which is a specific verb+resource pair. It also distinguishes itself from `compose_list` (non-swarm equivalent) and `stack_services` (drill into a single stack), making sibling differentiation explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: requires the target daemon to be a swarm manager, points to `compose_list` as the non-swarm alternative, and suggests `stack_services` for drilling into one stack. This gives clear context and alternatives.
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?
Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds behavioral context: that a locked manager cannot serve this API request, that the key is a sensitive credential, and the exact return structure. No 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded one-line purpose, followed by compact context in three sentences, each adding unique information about key usage, locked manager behavior, and security handling. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explicitly states the return format. It covers preconditions (unlocked manager), use cases (autolock enabled), and security handling, making it a complete reference for a parametrized tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters (100% schema coverage), so the baseline is 4. The description adds a return type specification (dict with "UnlockKey") but there are no parameter semantics to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return the swarm's current unlock key' — a specific verb and resource. It distinguishes itself from sibling swarm_unlock by explaining that the result's key is fed to swarm_unlock, making its role complementary rather than ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use conditions: only relevant when autolock is enabled, must be called against an unlocked manager, and how the output relates to swarm_unlock. References swarm_init/swarm_update parameters for context.
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?
Even though annotations already mark the tool as readOnly and non-destructive, the description adds valuable behavioral context: it warns about a large payload on busy hosts and describes the return structure. This goes beyond the annotations and gives the agent a clear expectation of output size and format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: the first defines the purpose, the second provides usage context and alternatives, and the third warns about payload size and return type. Every sentence adds unique value with no redundancy. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description fully covers what an agent needs: what the tool does, when to use it, what to expect in the return, and a caveat about large payloads. It is complete in context with sibling tools and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully documents the input (empty object). The description correctly implies no parameters are needed, meeting the baseline of 4 for no-parameter tools. No additional parameter explanation is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Summarize Docker disk usage' with breakdown of layer storage and per-object sizes for images, containers, volumes, and build cache. It also clarifies the equivalent docker command (`docker system df`). This clearly distinguishes it from sibling tools like `system_info` and `buildx_du`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool ('Use it to find what to reclaim before image_prune / container_prune / volume_prune / buildx_prune') and provides an alternative tool for different needs ('use system_info for daemon config and counts rather than sizes'). This is exemplary usage guidance.
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?
Beyond the readOnlyHint annotation, the description discloses that the call blocks until limit or timeout, that a quiet daemon would block indefinitely without timeout, and that SSH streams cannot be cancelled. It also explains memory (limit) and wall-clock (timeout) reasoning. This is rich behavioral context well beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: intro, blocking conditions, SSH caveat, usage idiom, and args. Each sentence provides necessary information, and the 'wait for event' idiom paragraph justifies the tool's existence concisely. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers return values (list of decoded event dicts, length <= limit), explains edge cases (idle stream, SSH), and gives practical usage guidance. It fully addresses the complexity of a streaming API, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'args' section provides a one-line meaning for all 5 parameters, which is essential given the 0% schema description coverage. Limit and timeout are clearly defined with defaults. 'since' and 'until' are minimally described as timestamps, and 'filters' is vague, but the description compensates for the schema's complete lack of field documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream real-time events from the Docker server', using a specific verb and resource. It distinguishes itself from sibling system tools (system_info, system_ping) by focusing on event streaming and clearly states the bounded behavior (limit/timeout). The 'wait for next matching event' idiom further clarifies a unique use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the core use case (waiting for a matching event) and even notes that 'there's no separate wait tool for this since the filtering this call already does covers it', thereby addressing alternatives. It also provides a caveat for ssh:// daemons, guiding when timeouts won't behave as expected, which is essential for correct usage.
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 context beyond the sparse annotations: it warns about password logging, mentions credential caching, details the return dict structure, and notes reauth behavior. It fully discloses security implications and side effects, with no contradiction to the readOnlyHint=false and destructiveHint=false 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose, security note, args list, and returns, and every sentence adds value. It is slightly longer than necessary but the security warning is important. A minor condensation could improve it, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal annotations, the description covers all necessary aspects: purpose, security, parameter semantics, return format, and relation to sibling tools. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 explains every parameter with meaningful context (e.g., reauth forces re-authentication, registry defaults to Docker Hub, dockercfg_path is a custom config). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Authenticate with a Docker registry,' a specific verb+resource statement that clearly defines the tool's action. It also distinguishes itself from siblings by explaining how credentials enable image_pull/image_push and are cleared by system_logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: prefer running `docker login` on the host instead, avoid calling from an agent loop due to security, and use system_logout to clear credentials. This clearly states when and how to use the tool versus alternatives.
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?
Beyond annotations (readOnlyHint: false, destructiveHint: false), the description discloses non-raising behavior and the subprocess nature via returncode. The cwd parameter description adds context about file copying when no local plugin. This adds significant context beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by a structured args list. Each sentence earns its place, and the parameter details are organized clearly without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes the return dict format ('returncode', 'stdout', 'stderr', 'truncated'), covers all parameters, and provides usage guidance. With no output schema, this is complete for a multi-parameter build tool with potential side effects (push, load).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by listing all 10 parameters with meaningful explanations, including an example for set_overrides ('app.platform=linux/amd64'), CLI flags for files ('-f'), and default values for cwd and timeout_seconds. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States the verb 'Build' with a specific resource: 'multiple targets defined in a bake file (HCL, JSON, or compose)' and differentiates from sibling buildx_build by mentioning 'for a single Dockerfile target use buildx_build'. This is a specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Use it for multi-target builds declared in docker-bake.hcl/compose files') and provides an alternative ('for a single Dockerfile target use buildx_build'). Also notes a key behavior: 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result.'
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?
Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses substantial behavioral traits: output capture with `--progress=plain`, remote build behavior (context copying via `.dockerignore`), rejects for certain `output`/`cache_to`/`cache_from`/`ssh` combinations that would resolve on the remote machine, and the fact that stdin is not forwarded. These specifics far exceed the annotations and are crucial for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence adds value. It starts with a one-line purpose, then a usage paragraph, then a per-parameter breakdown with examples and restrictions. For 24 parameters, this level of detail is appropriate and well-organized into a readable list. No filler or redundant content exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explicitly states the return shape as `{"returncode": int, "stdout": str, "stderr": str, "truncated": bool}`. It covers remote-host fallback behavior, unsupported stdin, file path resolution rules, and timeout default. For a tool with 24 parameters and no structured output definition, this description is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is technically 0% (no descriptions inside the schema), the tool description itself provides rich semantics for every parameter. It gives examples (e.g., `platforms` as `["linux/amd64", "linux/arm64"]`), constraints (e.g., `file` relative to server working directory, not `context`), and edge cases (e.g., `~` not expanded in `secret` `src=`). This far surpasses what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Build an image with BuildKit via `docker buildx build`.' It clearly distinguishes itself from the legacy `image_build` tool by enumerating the advanced capabilities (multi-platform, cache export, attestations, secrets, multi-stage targets), leaving no ambiguity about its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool: 'Replaces the legacy `image_build` tool when you need any of...' and also provides a when-not-to-use example (stdin tarball unsupported). It also documents that it always runs with `--progress=plain` and warns about remote-host restrictions, giving the agent clear decision-making context.
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?
Despite annotations only providing readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral context: non-zero CLI exits do not raise but are surfaced via returncode/stderr, config file handling and a buildx version requirement, and the side effect of `use=True` on subsequent buildx_build calls. This goes well beyond the annotations and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence adds value: a one-line purpose, a crisp usage justification, behavioral caveats, and a compact parameter list. The return format is included since there is no output schema. It is appropriately dense, with no filler or repetition of annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—9 parameters, nested objects, no output schema, and multiple behavioral caveats—the description is remarkably complete. It covers all parameters, return shape, error behavior, version constraint, and even related tool switching. An agent has nearly everything needed to invoke this correctly and understand the consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry all parameter meaning. It does: all 9 parameters (name, driver, driver_opts, use, bootstrap, platforms, config, node_name, append) receive brief but meaningful explanations, including transformations like driver_opts becoming `--driver-opt KEY=VALUE` and the buildx >= 0.17 requirement for config. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a new BuildKit builder instance.' It then clarifies the purpose and distinguishes this tool from siblings like buildx_use and buildx_build by explaining when a new builder is needed (multi-platform builds, cache export). This is a textbook clear purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool—'Needed when the default `docker` driver falls short'—and gives concrete use cases. It also explains the `use=True` workflow versus switching with `buildx_use`, and discusses the `bootstrap` behavior. This is strong when-to-use and alternative guidance.
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?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses the exact output parsing method (`--format '{{json .}}'`), the fields returned, the version requirement, and the error behavior on unsupported versions. This is valuable context that annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-dense: it opens with a clear purpose, then provides necessary detail on fields, usage context, version prerequisite, and parameter semantics. No extraneous content, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers every important aspect: what it does, what it returns, how it behaves with older versions, and what the parameter does. It is fully self-contained for an agent to decide when to call it and how to use the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter `builder` with no description. The description compensates fully with 'builder - Builder instance to read history from (defaults to the active builder)', clearly explaining the parameter's meaning and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb+resource: 'List recent build records (BuildKit build history)' and clarifies that it parses the output from `--format '{{json .}}'`. It also references the sibling tool `buildx_history_inspect` for drilling into a specific build, making its role distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when this tool is useful: 'finding a build to drill into with buildx_history_inspect', which reveals the intended workflow and alternative. It also provides a clear prerequisite (buildx >= v0.13) and warns about the failure mode on older versions, acting as a when-to-use/check guideline.
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?
Beyond the basic readOnlyHint/destructiveHint annotations, the description discloses critical non-obvious behavior: 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result.' It also clarifies the prerequisite that source tags must already be pushed and that append modifies an existing manifest. This adds substantial behavioral context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by key behavioral notes, then a neatly organized args list, and finally the return type. Every sentence adds value; the text is dense but not verbose, covering all necessary details without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9-parameter complexity and absence of an output schema, the description is remarkably complete. It includes prerequisites, side-effects, failure behavior, default timeout, return format, and pointers to related tools. No important aspect is left undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% schema coverage), but the description's 'args' section explains every one of the 9 parameters with meaningful details, such as `target` being 'Tag for the new manifest list (-t)', `dry_run` printing without pushing, and `descriptor_files` reading from files instead of refs. This fully compensates for the schema's lack of descriptions, even providing CLI flag mappings and usage nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a manifest list / OCI image index from existing per-platform tags.' It clearly distinguishes from siblings like buildx_imagetools_inspect by explicitly naming the verification tool and contrasting with docker manifest create/push.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use: 'Source tags must already be pushed; this only stitches them together' and provides an alternative: 'Replaces docker manifest create + docker manifest push.' It also recommends the next step: 'Verify the result with buildx_imagetools_inspect,' giving clear context on usage and alternatives.
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?
Annotations already mark destructiveHint=true, but the description adds crucial nuance: it deletes build cache unless keep_state=True, and it does not raise on non-zero CLI exit, requiring inspection of returncode/stderr. These are significant behavioral traits beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-line summary, brief behavioral notes, an args list, and a returns format. Every sentence adds value, with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description includes a precise return dict format. It covers side effects (cache deletion), error behavior (non-zero exit handling), and alternative tools, making it fully adequate for an agent to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates fully with an 'args' section explaining all 5 parameters, including the mutual exclusivity between name and all_inactive. Each parameter's meaning is clearly stated, adding value beyond the schema's type/default definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function ('Remove a builder instance') with a specific verb and resource. It distinguishes from related tools by referencing buildx_create and explicitly pointing out the alternative buildx_prune for cache reclamation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool versus alternatives: 'use buildx_prune to reclaim cache while keeping the builder.' It also notes the tool deletes builders made by buildx_create, giving clear contextual usage.
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 reveals important behavioral nuances beyond the annotations: without flags the change is limited to the CLI session, 'default' persists for the current context, and 'global_default' persists across all contexts. It also warns about the impact of switching the global default and offers a non-switching alternative, giving the agent full understanding of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose. The scoping details, usage tips, and parameter explanations each add value without redundancy. The format is clear, and the returns section neatly summarizes the output regardless of the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only three parameters, minimal annotations, and no output schema, the description covers everything an agent needs: purpose, scoping behavior, parameter meanings, return format, and explicit pointers to related tools. It is fully sufficient for correct invocation and decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for parameters (coverage 0%), but the description's 'args' section explains each parameter in detail: 'name' is the builder to activate (from buildx_list), 'default' persists for the current context, and 'global_default' persists across all contexts. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Select the active builder for subsequent buildx operations,' a specific verb and resource that clearly distinguishes this from siblings like buildx_list (which lists) and buildx_build (which builds). The scope is explicit: it changes the active builder for subsequent operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool versus alternatives with concrete guidance: use buildx_list to see available builders, and avoid switching the global default by passing a specific builder name to buildx_build's builder parameter. It also clarifies the scoping semantics (session, context, global), providing clear conditions for each mode.
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 discloses key behavior beyond annotations: it does not raise on non-zero CLI exit, requires inspecting returncode/stderr, and notes that project_dir is copied to the target host if no local plugin. These are valuable operational details not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with an intro sentence, usage distinction, behavioral note, parameter list, and return type. Each section adds necessary information without redundancy, and the length is justified by the parameter documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and minimal annotations, the description covers all necessary aspects: what it does, how it differs from siblings, error handling, parameter meanings, and return format. It is fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the schema has 0% description coverage, the 'args' section provides detailed semantics for all 7 parameters, including defaults, interpretation ('repeatable, -f', 'default: all'), and special behavior like project_dir copying. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds images for a compose project, specifically those declared in `build:` sections, and distinguishes itself from `compose_up(build=True)` by noting it does not start anything.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit alternative (`compose_up(build=True)`) for build-and-start workflow, and clarifies the tool's purpose as build-only. The mention of non-zero CLI exit behavior also informs usage expectations.
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 discloses key behavioral traits beyond the minimal annotations, including error handling (no raise on non-zero exit, inspect returncode/stderr), the FileExistsError refusal for container-to-host copies, and RuntimeError for unsupported hosts. These are valuable details not available 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense, covering all essential caveats and alternatives without redundancy. The clear structure (summary, caveats, fallback behavior, args list) justifies the length, and every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return values, error modes, fallback behavior, and parameter semantics thoroughly. Even without an output schema, the returns dict is specified, making the tool's behavior fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by documenting each parameter's semantics in the args list (e.g., 'source - SERVICE:SRC_PATH or a host path', 'index - Container index when the service has multiple replicas'). This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence clearly states the tool's function ('Copy files/folders between a service container and the server host's filesystem') and the description distinguishes it from related archive tools by explicitly naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use this tool (e.g., copying to stdout) and recommends alternatives (`container_archive_get`, `container_archive_put`, `container_archive_get_to_file`). It also explains the fallback to real CLI for ssh:// targets, making usage context clear.
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?
Goes well beyond the destructiveHint annotation by specifying that images are kept, named volumes are only removed with the volumes flag, and that the tool does not raise on non-zero CLI exit (requiring inspection of returncode/stderr). These are non-obvious behavioral traits that an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening line, a usage comparison, a key behavioral note, and a compact bulleted parameter list. Every sentence adds value and there is no redundancy; the length is justified by the number of parameters and the need to clarify destructive behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explicitly documents the return format as a dict with returncode, stdout, stderr, and truncated. It covers all 7 parameters, the destructive semantics, and the error behavior, making the tool fully self-contained for an agent to use safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 fully by explaining every parameter: project_dir, files, project_name, profiles, volumes, remove_orphans, and timeout_seconds. Each parameter gets a concise one-line semantic explanation, which is critical for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Stop and remove containers, networks (and optionally volumes) for a compose project' and identifies it as the inverse of compose_up. It names the exact resource (compose project) and actions, making it easy to distinguish from sibling tools like compose_stop and compose_restart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use compose_stop to stop without removing anything' and notes that volumes are only removed with volumes=True. This clearly tells the agent when to choose this tool versus alternatives, which is exactly what usage guidelines should do.
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?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral details: immediate execution with no grace period, non-raising behavior on CLI errors, and the exact return shape (returncode/stdout/stderr/truncated). This significantly enriches the agent's understanding beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a usage alternative note, a failure-handling note, a compact args list, and a returns line. Every sentence carries necessary information, and the most critical usage guidance is front-loaded. No waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters and no output schema, the description covers all bases: parameter meanings and defaults, return format, error behavior, and when to prefer an alternative. It provides a self-contained guide for invoking this tool correctly, making it fully contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions (schema_description_coverage=0%), but the description's 'args' section thoroughly explains all six parameters, including defaults (e.g., services default all, signal default SIGKILL) and examples (SIGTERM, SIGHUP). It even notes the behavior of project_dir when no local plugin is present. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send a signal') and resource ('compose project's containers'), clarifies the default signal (SIGKILL), and distinguishes itself from compose_stop by explicitly recommending the latter for clean shutdown. This makes the purpose unambiguous and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on when to use this tool versus compose_stop ('prefer compose_stop for a clean shutdown'), and provides handling instructions for non-zero CLI exits (inspect returncode/stderr). This is strong, actionable usage guidance that covers both selection and error handling.
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?
Annotations only declare readOnlyHint=true and destructiveHint=false. The description adds crucial behavior: 'never follows', 'always returns promptly', 'Log text arrives on stdout', and especially 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result.' This goes well beyond annotation hints and helps the agent interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a leading summary paragraph front-loads the core behavior, followed by a compact arg list. Every sentence adds value—no filler. The parameter explanations are grouped logically and remain scannable despite covering 8 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, no output schema, and 0% schema description coverage, so the description must carry full weight. It does: it covers all params, return values (dict with returncode/stdout/stderr/truncated), failure behavior (non-zero exit not raising), and placement among siblings. This is fully adequate for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description includes an 'args' block that explains every parameter with concrete meaning: 'project_dir - Dir with the compose file...', 'services - Restrict to these services...', 'tail - Lines per container (default 200), or the literal "all"...', etc. This fully compensates for the bare schema and supplies format hints for `since`/`until`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Fetch a bounded slice of logs from a compose project (never follows).' It clearly distinguishes from sibling tools by name-checking `container_logs` and `service_logs` for other log sources, and the 'never follows' qualifier adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'For one container's logs use `container_logs`; for a swarm service use `service_logs`.' It also explains when this tool is appropriate ('bounded and non-following by design, so it always returns promptly'), giving the agent clear decision criteria.
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?
Annotations only indicate readOnlyHint=false and destructiveHint=false. Description adds substantial behavioral context: what happens to processes (frozen), what resources are retained (memory, network endpoints, state), and crucially the non-raising CLI behavior requiring returncode/stderr inspection. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
First sentence states the core action. Second provides key trade-offs and alternatives. Third covers error behavior. Args list is concise and directly follows. Every sentence earns its place; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage distinctions, behavioral nuances (process freezing, resource retention), error handling, parameters with defaults, and return format (dict with returncode, stdout, stderr, truncated). No output schema exists, so the return description is sufficient. Complete for a compose control tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description includes an args section with clear semantics and defaults for all 4 parameters: services (restrict, default all), project_dir (default server cwd, remote copy note), files (explicit -f paths), project_name (override). This fully compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool pauses compose project containers ('Pause the containers of a compose project') and explicitly differentiates from siblings: resume with compose_unpause, stop with compose_stop, and stop+delete with compose_down. The verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use this tool versus alternatives, including semantic differences ('Paused containers stop consuming CPU but keep memory, network endpoints, and state') and direct references to compose_unpause, compose_stop, and compose_down. Also notes error behavior (does not raise on non-zero CLI exit) and how to inspect results.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it explains the published=None case, the RuntimeError on CLI failure, and the exact return schema. It also notes project_dir is copied to the target host when no local plugin exists, which goes beyond annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then organized into args and returns sections. Every line earns its place: parameter meanings, defaults, exceptions, and return semantics. It is detailed but not redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 params, no output schema, and no enum constraints, the description provides everything an agent needs to select and invoke correctly: purpose, alternatives, failure behavior, param semantics, and return structure. It is complete for safe, correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the full parameter burden. It does so thoroughly: each of the 7 parameters is named with meaning and defaults (protocol, index, project_dir, files repeatable, project_name override). The return dict is also fully documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'Resolve' and resource 'host binding for a service's container port', clearly distinguishing it from container-level tools. It also frames it as 'The compose equivalent of `docker port`', which disambiguates it from sibling compose commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when not to use this tool: 'For non-compose containers read `container_inspect`'s NetworkSettings.Ports instead.' This gives a clear alternative and contextual boundary, which is exactly the kind of guidance needed.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds critical behavior beyond that: 'Does not raise on a non-zero CLI exit: services comes back empty — inspect raw.stderr.' It also explains the return format and that output is parsed from `--format json`, giving the agent a full picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly efficient: one sentence for purpose, one for differentiation, one for error behavior, then a concise args list and return type. Nothing is redundant; it front-loads the essential purpose and immediately distinguishes from siblings, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description is complete: it explains the return dict, the error behavior (empty services, inspect raw.stderr), and parameter defaults. It covers all necessary context for an agent to invoke it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully with an 'args' section that explains every parameter (project_dir, files, project_name, services, all). Each has a clear meaning and default, e.g., 'project_dir - Dir with the compose file (default: server cwd; copied to the target host if no local plugin)'. This provides complete semantic coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List containers in a compose project, parsed from `--format json`.' It clearly distinguishes from siblings by stating 'compose_list enumerates projects, and container_list covers non-compose containers.' This is a precise, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names alternatives and when they apply: 'compose_list enumerates projects, and container_list covers non-compose containers.' It also provides behavioral guidance for error handling ('Does not raise on a non-zero CLI exit... inspect raw.stderr'), which helps the agent know when and how to use the tool.
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 discloses key behavioral traits beyond the annotations: it does not recreate containers or apply config changes, it stops then starts services, and it describes the SIGTERM/SIGKILL grace period controlled by stop_timeout_seconds. It also explains the project_dir behavior when no local plugin is present. The return dict is specified, which is valuable since there is no output schema. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured. It starts with a clear one-sentence summary, then usage guidance, then an alternative, followed by a compact parameter list. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six optional parameters and no output schema, the description is remarkably complete. It covers the exact operation, when to use it, alternatives, all parameter semantics, the return format, and important behavior like SIGKILL and file copying. It is sufficient for an agent to select and invoke the tool correctly without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions for parameters, but the description provides a complete arg list with meaningful explanations for all six parameters: project_dir, files, project_name, services, stop_timeout_seconds, and timeout_seconds. This fully compensates for the absent schema descriptions and adds context like defaults and repeatability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Stop then start services without recreating containers or applying config changes.' This clearly distinguishes compose_restart from compose_up, which handles config changes, by explicitly naming the alternative. The purpose is unambiguous and strongly scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage guidance: 'Use this to bounce a service (e.g. to pick up a runtime file change or clear an in-memory state).' It also gives a clear when-not-to-use direction: 'If the compose file has changed (new image, environment, volumes, ports) use compose_up instead.' This directly addresses alternatives and exclusion criteria.
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?
Annotations already signal readOnlyHint=false and destructiveHint=false. The description adds crucial behavioral context by noting it starts containers 'without recreating them' and that project_dir is 'copied to the target host if no local plugin.' It also documents the return dict, providing transparency beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: one sentence for purpose, one for usage boundaries, and a terse arg/returns list. Every sentence earns its place, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description covers purpose, alternatives, all parameter semantics, and the return structure. It provides enough context for an agent to invoke compose_start correctly without needing external docs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining all five parameters with defaults and semantics, e.g., 'project_dir (default: server cwd; copied to the target host if no local plugin)' and 'timeout_seconds (default 600s).' This adds meaning far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear statement of action and object: 'Start existing (stopped) containers of a compose project.' It explicitly contrasts with compose_stop and compose_up, making its unique scope immediately apparent and distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool versus alternatives: 'Counterpart to compose_stop' and 'Use compose_up to (re)create containers from the compose file.' This gives direct, actionable guidance on tool selection.
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?
Annotations only provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: requires a swarm manager, configs are not encrypted at rest, data must be raw bytes with encoding advice, and configs are immutable with a prescribed update process. It also describes the return dict structure, going well beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise opening, purposeful explanatory sentences, a clear args section, and a returns line. Every sentence adds value—no fluff. Despite being detailed, it remains focused and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param tool with no output schema, the description is complete: all parameters are explained, the return value is specified, usage context and constraints are covered, and the immutability workflow is fully described. It leaves no critical gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by documenting all four parameters: name (unique within swarm), data (raw bytes, encode strings), labels, and templating with an example format. This adds meaning far beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create an immutable Swarm config object', and immediately distinguishes itself from secret_create and config_remove by explaining configs are for non-sensitive files. This clearly states what the tool does and differentiates it from relevant siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool (non-sensitive config files) and when to use secret_create instead (credentials/keys). It also provides an update workflow: create a new config, update the service, then remove the old config with config_remove. This is explicit usage guidance with alternatives.
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?
Annotations already indicate a safe read operation, but the description adds important behavioral context: configs include base64-encoded Spec.Data unlike secrets, and a swarm manager is required. This goes beyond annotations and warns about data volume, improving transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, focused paragraphs front-load the core action. Every sentence delivers value—usage context, filter keys, return shape—with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description provides all necessary operational details: prerequisite, filter syntax, and return document structure. The agent can confidently invoke this tool without additional lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for the 'filters' parameter. The description fully compensates by explaining the parameter's purpose, valid filter keys, and the default behavior when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List swarm configs,' using a specific verb and resource. It distinguishes itself from config_inspect and config_remove, and notes the difference from secrets, making its purpose unambiguous among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the prerequisite ('requires a swarm manager'), provides valid filter keys, and directs users to config_inspect for single-config lookup. This gives clear when-to-use and when-not-to-use guidance, including an alternative tool.
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?
Beyond annotations (readOnlyHint, destructiveHint), the description discloses that bytes are returned in-band, that MCP base64-encoding creates a 32 MiB default cap, that exceeding it aborts with ValueError, and that the return is a dict with `archive` and `stat` keys. This is richer behavioral context than typical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: one sentence for purpose, one for usage guidance, then a compact argument list. Every sentence earns its place, and the format aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter read-only tool without an output schema, the description covers purpose, usage, parameters, and return format. It also names the alternative for large paths, making the tool self-contained and sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates completely by explaining each parameter: `id_or_name` (container id/name), `path` (inside container), and `max_bytes` (abort if exceeded, default 32 MiB). It adds meaning far beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Retrieve a file or directory from a container as a tar archive, returned in band.' It clearly distinguishes this tool from the sibling `container_archive_get_to_file` by explicitly contrasting in-band vs. streaming to host path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'For large paths prefer `container_archive_get_to_file`' and explains why (in-band bytes capped because MCP base64-encodes them). This provides a clear when-to-use and when-not-to-use directive with a named alternative.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral details: streams straight to disk with no in-band byte cap, file written by the server's user, '~' expansion, and refusal of existing files unless overwrite=True. This adds meaningful context not present in structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it starts with a direct purpose statement, then gives rationale for use, then lists parameters in an organized block. Every sentence adds value—no filler or redundancy—striking an excellent balance between completeness and efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of output schema, the description covers all critical aspects: what it does, when to use it, behavior around file overwrites and path expansion, and the return value structure. It is self-sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by providing clear one-line meanings for each parameter: id_or_name, path, dest_path, and overwrite (including default behavior). This gives the agent complete understanding of expected inputs beyond bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear verb ('Retrieve') and specific resource ('file or directory from a container as a tar archive written to a file on the server host'). It immediately distinguishes itself from sibling tools by noting it is the 'File-writing variant of container_archive_get' and contrasts with 'container_export' for whole filesystem use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'prefer it for anything large, since in-band bytes are base64-encoded by MCP'. It also provides a clear alternative for a different use case: 'For the whole filesystem use container_export'. This gives decisive guidance on selection among related tools.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important runtime behavior: 'The container is paused by default during the snapshot to ensure filesystem consistency — set `pause=False` only if the container cannot be paused.' It also explains the `changes` semantics and states the return value is the full inspect payload containing the new image id. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. The first sentence defines the action, the second gives use cases and alternatives, and the third explains pause behavior. The args list is terse but informative, with each parameter receiving a short meaningful phrase. No filler or redundant content is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 8-parameter tool with no output schema. The description covers all parameters, explains the pause default and exception, describes the `changes` input format, and states the return type ('dict - The new image's full inspect payload'). It provides enough context for an agent to invoke the tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has no parameter descriptions (0% coverage), the description's dedicated args list explains every single parameter: id_or_name, repository, tag, message, author, pause, changes, and conf. It even gives an example Dockerfile instruction format for `changes`. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, unambiguous verb phrase: 'Snapshot a container's current filesystem state as a new image.' It clearly identifies the resource (container) and the outcome (image). The description also differentiates from sibling tools by explicitly recommending `image_build` for repeatable builds, which distinguishes this ad-hoc snapshot workflow from declarative image creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Useful for capturing a debugging state or saving manual changes made inside a container.' It also gives concrete alternative guidance: 'For repeatable builds use `image_build` with a Dockerfile instead; publish the result with `image_tag` + `image_push`.' It additionally explains when to disable pause, giving a clear if-then usage rule.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond that: it compares only the writable container layer and excludes volumes/bind mounts. This is exactly the kind of nuance an agent needs to interpret results correctly. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The first sentence states the core purpose, followed by usage context, a key limitation, and structured args/returns. Every sentence adds information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, this description is complete. It covers purpose, when to use, a crucial limitation, parameter semantics, and return format. An agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does thoroughly: 'args: id_or_name - The container id or name' fully explains the only parameter. It also documents the return format with the Kind meaning, filling the gap left by the missing output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'List filesystem changes a container has made relative to its image.' This clearly distinguishes it from sibling tools like container_inspect or container_logs. It's unambiguous and immediately actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use it to audit what a container wrote before container_commit or container_archive_get, or to debug unexpected writes.' It also provides a key exclusion: 'files in volumes and bind mounts never show up,' which helps an agent decide against using it when such paths are relevant.
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?
Beyond the minimal readOnly/destructive annotations, the description discloses important behavioral context: shell metacharacter risks, the exact return structure ({exit_code, output}), and how demux alters the return format. This goes well beyond what annotations alone offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line purpose, a compact security note, and a clear args list followed by return semantics. Every sentence is informative, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no output schema and no parameter descriptions in the schema, this description is self-sufficient. It covers all parameters, return behavior, and a key security caveat, leaving no major gap in the agent's ability to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully by listing all 12 parameters with concise, meaningful explanations. It also adds crucial per-parameter guidance for `cmd` (prefer exec-form argv) and `demux` (separate stdout/stderr), making the schema much more usable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Run a command inside a running container', which names the specific verb, resource, and scope. It also explicitly directs compose-service users to `compose_exec`, distinguishing this tool from a close sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance to prefer `compose_exec` for compose services, and provides security-driven instructions on using exec-form argv when cmd elements are agent-controlled. This clearly communicates when and how to use the tool versus alternatives.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses many behavioral details: the tar is a flat filesystem snapshot with no image metadata, the file write behavior (server user, ~ expansion, refusal of existing files without overwrite), the byte cap in in-band mode with ValueError aborts, and the return format. This significantly aids the agent in anticipating side effects and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but organized: a high-level summary, explicit sibling alternatives, mode-specific behavior, and a parameter list. Every sentence adds value, and the structure makes it easy to parse. It is not bloated despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two output modes, overwrite logic, byte caps), the description fully covers selection criteria, behavior, parameter semantics, and return values. The absence of an external output schema is compensated by an explicit 'returns' description. No important context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 does so thoroughly with an 'args' section explaining each parameter's meaning, default, and behavior (e.g., dest_path omission for in-band mode, overwrite default False, max_bytes cap and abort). This adds essential semantic value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool exports a container's filesystem as a tar archive, with two modes: to a file on the server host or in band. It explicitly distinguishes from sibling tools by naming image_save and container_archive_get and explaining their different purposes, making the tool's specific role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it recommends image_save for restorable archives, container_archive_get for single files/directories, and explains when to use dest_path vs. in-band mode. It also mentions the fallback justification for in-band mode (containerized server without a writable host path).
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 goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by explaining the destructive nature: 'default SIGKILL — immediate, no graceful shutdown', and documenting edge-case behaviors like failing with a conflict error and refusing to signal its own container in containerized servers. This gives the agent a rich behavioral model without needing to infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it leads with the core action, then moves to usage guidance, then lists args and returns. Every sentence earns its place—no fluff, no repetition. The args block is formatted cleanly and is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (signals, error cases, containerized caveat) and no output schema, yet the description covers all critical aspects: purpose, default behavior, usage alternatives, error conditions, return value, and parameter semantics. There is no gap that would leave an agent uncertain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 0%, the description fully documents both parameters. It defines id_or_name as 'The container id or name' and signal with examples ('SIGHUP', '9') and its default (SIGKILL). This adds crucial semantic detail that the bare schema (signal: string, default null) does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Send a signal to a running container', and immediately clarifies the default behavior (SIGKILL, no graceful shutdown). It actively differentiates from sibling tools like container_stop by framing this as the force-kill/non-graceful alternative, making the purpose unmistakably distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit and actionable: 'Use it to force-kill a container that ignores container_stop, or with signal to poke a process without stopping it... For a normal shutdown prefer container_stop.' It also covers failure modes (conflict error if not running, refusal to signal own container), providing complete when-to-use and when-not-to-use context.
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 rich behavior beyond the readOnlyHint annotation: it explains default running-only behavior, how sparse affects output, the meaning of ignore_removed, and the managed_only label filter. This fully discloses the tool's behavioral traits and return semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: basic behavior, alternative tool guidance, parameter list, and return value explanation. Every sentence adds value, and the length is justified by the complexity of the tool (8 params, multiple behaviors).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description thoroughly explains return values ('full inspect payloads by default' vs. 'abridged list entries' with sparse). It also covers edge cases like removed containers and managed-only filtering, making it complete for a container listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, but the description provides a detailed 'args:' block explaining all 8 parameters, including semantics like 'since'/'before' being id/name based and 'filters' being attribute filters. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource ('containers on the daemon') and explicitly notes the default running-only scope. It also distinguishes itself from sibling tools by pointing to 'compose_ps' and 'service_ps' for alternative grouping/use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Pass all=True to include stopped containers' and directs users to 'compose_ps' for compose projects and 'service_ps' for swarm services. This clearly states when to use this tool versus alternatives.
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?
Annotations already declare this as a read-only, non-destructive operation. The description adds substantial behavioral context beyond that: the 32 MiB cap and ValueError, follow-mode termination conditions (limit_lines, timeout_seconds, container exit), and the SSH stream caveat. It discloses failure modes and limits, which is exactly what an agent needs to trust the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-sentence overview, then focused paragraphs on behavior, limits, and caveats, followed by a clean parameter list. Every sentence delivers actionable information without redundancy. It is dense but not verbose, and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters and two modes, the description covers all critical aspects: mode differences, limits, edge cases (SSH daemon, context size), and return type. It also notes the output schema exists, so the agent knows additional return details are available. No gaps are apparent for an agent to safely invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the sole source of parameter meaning. It explains each parameter's role and interaction (e.g., 'limit_lines/timeout_seconds apply only in follow mode', 'until only in snapshot mode'). It also defines 'tail' values (integer or 'all') and defaults, effectively compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the logs of a container' and immediately distinguishes two modes (snapshot vs. follow). It also contrasts with sibling tools like service_logs, making its scope clear. This goes beyond a generic statement and gives an agent precise understanding of what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use alternative tools (service_logs) and provides practical guidance on parameter choices ('Prefer an integer tail... over tail="all"'). It also warns about the SSH caveat and recommends snapshot mode for hard time bounds, giving clear exclusions and context for decision-making.
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?
Annotations already indicate destructive behavior, but the description adds valuable context: running containers are never affected, filter key semantics are explained, and a preview workflow is recommended. This goes well beyond the structured annotations and aligns with the destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, and every subsequent sentence adds distinct value—scope, preview recommendation, filter details, alternative cleanup path, and return format. It is detailed without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and lack of output schema, the description fully covers behavior, safety, parameter semantics, return value, and alternative tools. The agent has everything needed to invoke it correctly and avoid unintended deletions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only lists 'filters' with no description, while the tool description fully explains the parameter: 'Narrow which stopped containers to remove; omit to remove all stopped' and documents valid filter keys ('until' with RFC3339/duration format, 'label'). This significantly compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove all stopped containers to reclaim disk space.' This clearly states what the tool does and its outcome, distinguishing it from related tools like container_remove, image_prune, and network_prune.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Only removes containers that are not running'), how to preview before running ('Use container_list(all=True)'), and points to an alternative for broader cleanup ('prune_managed prompt'). This gives the agent clear decision guidance.
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?
Despite annotations already marking destructiveHint=true, the description adds substantial context: deletion of the writable layer, refusal to remove running containers without force, and refusal to remove the server's own container when containerized. It also explains volume behavior and force semantics, which are not inferable from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: a one-sentence summary, a focused paragraph on key behaviors and edge cases, then a clean arg list and return type. No redundancy or fluff; every sentence provides distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, side effects, edge cases (running containers, own container), parameter semantics, and return value. Given the tool's complexity and 4 parameters, this is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully with an 'args' section explaining every parameter: id_or_name, volumes (anonymous only), link, and force (with default). This adds meaning beyond raw schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Remove a container, deleting its writable layer.' It clearly distinguishes from image_remove and clarifies that named volumes are not removed, setting it apart from related tools like volume_remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit alternatives and limitations: 'the image is untouched (`image_remove` deletes images); named volumes are never removed — volumes=True only covers anonymous ones.' Also states running containers are refused unless force=True, giving concrete usage conditions. This goes beyond vague 'use for removal' guidance.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behavior: the container's id, state, and configuration remain unchanged; it fails with a conflict if the name is taken; and it returns the full inspect payload. This is far more informative than the bare annotations and sets clear expectations for side effects and outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet complete, with a clear opening statement, a usage rationale, a clarification about a related tool, and a well-organized args/returns section. Every sentence contributes valuable information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter rename operation, the description covers purpose, usage context, parameter semantics, an error condition, and the return value. With no output schema, this is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has no property descriptions (0% coverage), the description includes an 'args' section that clearly explains each parameter: `id_or_name` is the container id or name, and `name` is the new name with the constraint that it must not be in use. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Rename a container in place' with the specific resource and verb, and distinguishes itself from `image_tag` by noting it's about images, not container names. This fully clarifies what the tool does and sets it apart from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use it ('free up or claim a container name', e.g., before starting a replacement) and mentions the conflict error for taken names. It also explicitly compares to `image_tag`, providing an exclusionary alternative. This gives clear guidance on when to use this tool vs. others.
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?
Beyond the readOnly/destructive hints, the description discloses the STOPSIGNAL behavior, the SIGKILL timeout, the subsequent restart, and the refusal to restart the server's own container. It also states the return value (full inspect payload), adding substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a behavior paragraph, and an args/returns section. Every sentence provides essential information without redundancy, making it both concise and comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters and no output schema, and the description covers both parameters, explains the return type, and describes edge cases. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description lists both parameters with clear meanings: 'id_or_name - The container id or name' and 'stop_timeout_seconds - Seconds between the stop signal and SIGKILL (default 10)'. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Restart a container: stop then start again in one call,' clearly identifying the verb and resource while distinguishing from separate stop/start operations. It also mentions the self-restart refusal, further clarifying the tool's exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use container_stop/container_start to do the halves separately,' naming the alternative tools. It also includes a when-not scenario: the server refuses to restart its own container when containerized, providing clear usage boundaries.
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?
Beyond the annotations (which only state readOnlyHint=false and destructiveHint=false), the description discloses that detach=False blocks until exit and returns output, that long-running images need detach=True, and that created containers get provenance labels. It also clarifies the `remove` option only applies with detach=False, adding meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line summary and key usage distinctions before the structured arg list. Each parameter line is short and information-dense; despite length, no redundant sentences appear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, when to use alternatives, blocking vs detach behavior, side effects, return format, and a pointer for the full `extra_kwargs` set. Given the output schema exists and the large parameter count, no major gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description's args section compensates by listing all 22 parameters with plain-language meanings. It includes concrete examples for `ports` and `restart_policy`, and notes important constraints like `remove` only with detach=False and `extra_kwargs` pointing to `docs_lookup`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening line clearly identifies the action (run a container from an image) and the resource (container), with the `docker run` analogy. It explicitly distinguishes from `container_create` and `container_exec`, which are the most relevant siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to `container_create` for prepare-only and `container_exec` for running commands in an existing container. It also gives concrete guidance on `detach` for long-running images, helping choose between blocking and background invocation.
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?
Beyond minimal annotations (readOnlyHint=false, destructiveHint=false), the description discloses that calling on an already-running container is a no-op (daemon returns 304, no error) and states the return payload is the container's full inspect result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded summary, explicit guidance, and a clear args/returns section. Every sentence adds value without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema), the description covers purpose, usage, edge-case behavior, and return format. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero description coverage, but the description fully defines the only parameter: 'id_or_name - Container id (full or short) or name'. This compensates completely for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States exactly what it does: 'Start an existing stopped container.' Differentiates from container_run and container_restart, making its specific role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: use for containers previously created or stopped, use container_run to create+start, use container_restart to stop+start. Also explains behavior for already-running containers.
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?
Despite readOnlyHint=true annotations, the description adds crucial context by explaining that CPU percent must be computed from cpu_stats and precpu_stats deltas. This is non-obvious behavioral information beyond the annotations and clearly benefits the user.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and structured, with a clear purpose statement, usage guidance, and typical args/returns sections. Every sentence adds value without redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers the operation, return payload expectations, and key computation caveats. It also references alternatives, making it fully self-contained for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the input schema only shows a required string id_or_name, the description's args section explicitly defines it as 'The container id or name', fully compensating for the 0% schema description coverage. This leaves no ambiguity about the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a one-point-in-time resource-usage snapshot for a container, with the specific distinction of being non-streaming. This verb+resource combination distinguishes it well from container_top (process listing) and other container tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs users to prefer the docker-stats:// resource for a pre-computed summary and container_top for process listing, offering clear alternatives and when to use them. The non-streaming note also sets expectations for behavior.
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 exposes behavioral details beyond the minimal annotations: the stop signal sequence (STOPSIGNAL then SIGKILL after timeout), the default SIGTERM, and the refusal to stop its own container when running containerized. This adds significant context and no contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, using short paragraphs and an args/returns section. Every sentence adds value, and there is no unnecessary repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description specifies the return type (dict) and points to State.ExitCode for exit code. It also covers a key edge case (self-container refusal). The description is thorough for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining both parameters: id_or_name as container id or name, and stop_timeout_seconds as seconds between stop signal and SIGKILL, including the default value 10. This adds real semantic meaning beyond the schema's bare type declarations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Gracefully stop a running container', clearly stating the verb and resource. It also distinguishes itself from container_kill, container_restart, and container_pause, so the agent can immediately tell what this tool does uniquely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Prefer this over container_kill for a clean shutdown' and 'Use container_restart to stop and start again in one call, or container_pause to freeze processes without stopping.' Also mentions the self-container refusal edge case, giving clear when-to-use context.
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?
Discloses that the daemon runs ps on the host, meaning no shell or ps binary is needed in the image—a key behavioral trait not evident from schema or annotations. Also specifies the failure condition. Annotations already indicate read-only, and the description adds valuable implementation context 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by usage guidance, parameters, and return format. Each sentence adds value; no filler or redundancy. The length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary context: the exact operation, prerequisites, alternatives, parameter meanings, return structure, and failure modes. Despite having no output schema, the description explains the return dict format explicitly. It is entirely complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameter descriptions (coverage 0%), but the description fully compensates by explaining id_or_name as container id/name and ps_args as extra ps arguments with an example 'aux' and default behavior. This is more than sufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the processes running inside a container' with a specific verb and resource. It differentiates from siblings by explicitly contrasting with container_exec and container_stats, making the tool's unique 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use it ('Works on any running container without executing anything in it'), when not to use it ('Use container_stats for resource usage rather than process lists'), and contrasts with alternative container_exec. Also notes a failure condition ('Fails if the container is not running').
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?
Beyond the readOnly/destructive annotations, the description discloses non-obvious behaviors: never raises on timeout, always returns `met` and `timed_out`, different condition modes fill different result fields, health semantics when no HEALTHCHECK exists, and log-match substring/regex behavior including a ReDoS warning. This is rich, context-adding transparency with no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Though lengthy, the description is efficiently organized into clear sections: the core purpose, a shared contract, mode-specific details, health and log-match semantics, and an args/returns reference. Every section earns its place and is 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is exceptionally complete for a complex multi-mode tool with no output schema. It explains the return dict, which fields each mode populates, how edge cases resolve (e.g., exit before health, exit before log match), and how poll_interval caps against timeout. No significant context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions, but the description's args section thoroughly explains each parameter: id_or_name, the until enum with defaults, timeout_seconds, poll_interval with capping behavior, pattern semantics, and regex. This adds full meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Block until a container reaches a condition: stopped, "healthy", or its logs contain a pattern.' It enumerates the distinct condition modes and explicitly distinguishes from siblings by pointing to compose_wait for compose projects and service_wait for swarm services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: 'For a compose project use compose_wait; for swarm services use service_wait.' It also gives mode-specific behavior, timeout semantics, and edge cases, making appropriate usage clear.
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 discloses important behaviors beyond annotations: it notes that the tool does not retarget the docker-py client, does not raise on non-zero CLI exit (returns result dict instead), and raises ValueError on commas to prevent injection. All this enriches the agent's understanding of what actually happens during invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: an initial concise purpose paragraph, followed by a bulleted argument list, and a return structure. Every sentence adds value, covering purpose, caveats, parameter requirements, and output format without extraneous filler. Despite being detailed, it remains front-loaded and efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no schema coverage, no output schema), the description is comprehensive. It explains the return dict fields, error behavior, connection to sibling tools, and critical injection protection, leaving no gaps that would hinder correct invocation. This is complete for all practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully explains all 7 parameters: each argument gets a clear description, including constraints like 'may not already exist' or 'no commas', and an example for the docker_host parameter. It also clarifies that skip_tls_verify must be set directly and cannot be smuggled through the command, providing all necessary info for correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new Docker CLI context pointing at a daemon endpoint' and further explains it 'Registers a named endpoint for the CLI; switch with context_use, enumerate with context_list.' This distinct verb and resource, plus explicit differentiation from sibling tools (context_use, context_list), makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context on when to use the tool: it registers a named endpoint for the CLI, clarifies it does not retarget the server's docker-py client, and warns about non-zero exit handling (inspect returncode/stderr). It also states constraints like 'must not already exist' and the comma injection risk, effectively explaining both appropriate usage and caveats.
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?
Beyond the destructiveHint=true annotation, the description discloses critical behavior: it deletes only CLI connection metadata while leaving the daemon untouched, and it does not raise on non-zero CLI exits, requiring inspection of returncode/stderr. These details are valuable and not present in the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and compact. It opens with a clear one-line purpose, uses a concise paragraph for behavioral nuances, and lists parameters/returns in a readable format. Every sentence contributes meaningful information without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers all essential aspects: purpose, side effects (deletion scope), edge case (current context), error handling (non-zero exit), parameters, and return value shape. No output schema exists, so documenting the return dict is especially valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining each parameter: 'name - Context name to remove' and 'force - Force removal even if the context is the current one'. This adds meaning beyond the raw schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Remove a Docker CLI context', using a specific verb and resource that clearly differentiates it from sibling tools like context_create, context_list, context_inspect, and context_use. It also clarifies that it only affects CLI metadata, not the daemon, further pinning down its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete guidance on when this tool is appropriate and how to handle the current context: 'The current context needs force=True (or `context_use` another first)'. This explicitly offers an alternative approach via a sibling tool, satisfying the when-to-use vs alternatives criterion.
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 discloses a key behavioral trait beyond the annotations: it does not retarget the long-lived docker-py client, so SDK-backed tools retain their startup endpoint. This is critical for an agent to understand the tool's real impact. The annotations (readOnlyHint=false, destructiveHint=false) are consistent with a mutation that is not destructive, and the description adds important context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It leads with the core purpose, includes a critical caveat, and then provides args/returns. Every sentence adds value without redundancy. The format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is complete. It covers the purpose, the limitation, parameter semantics, and return format. It also cross-references related tools. No essential information is missing for an agent to select and use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description fully explains the single parameter: 'name - Existing context name to set as default.' This conveys both the parameter's purpose and a constraint (it must exist), which is sufficient for a simple string parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set the active Docker context for the CLI on the host running this MCP server.' This specifies a verb (set), resource (active Docker context), and scope (CLI on host), distinguishing it from related context management tools like context_create and context_list, which are explicitly referenced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It notes that SDK-backed tools are not retargeted and suggests restarting with DOCKER_HOST/DOCKER_CONTEXT instead. It also points to context_create for creation and context_list for listing, giving clear alternatives.
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?
Goes well beyond annotations by disclosing auth behavior ('sends no auth and does NOT read the local Docker credential store') and failure modes for private repos. ReadOnlyHint annotation is consistent with the read-only nature described, with no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: a one-line summary, a concise behavioral note with alternatives, and a structured args/returns block. No fluff, well-organized, and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists typical return fields ('description, star_count, pull_count, last_updated, is_private, etc.'), covers auth/error behavior, and contextualizes alternatives. Fully sufficient for a simple metadata-fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the `repository` parameter with examples ('library/alpine' or 'myorg/myimage'), adding format and naming conventions beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb+resource pair: 'Fetch Docker Hub metadata for a repository.' It distinguishes from siblings by explicitly redirecting tag-related queries to `registry_tags` and `hub_tags`, making the tool's unique scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage constraints ('Public repos only', 'private repos return 404/401') and explicitly names alternatives for different needs ('use registry_tags for tag lists... hub_tags for Hub tag details'). This is clear when-to-use and when-not-to-use guidance.
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?
Beyond the readOnlyHint/destructiveHint annotations, the description discloses key behaviors: it hits a specific API (hub.docker.com), sends no auth, does NOT read ~/.docker/config.json, and private repos return 404/401. It also mentions pagination capped at 50 pages. These are non-obvious traits that add significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but information-dense. It front-loads the purpose, then covers usage, parameters, and return format in a clear structure. Every sentence contributes new information—no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema), but the description covers all necessary context: purpose, usage alternatives, auth behavior, parameter semantics, and return format. Even without a formal output schema, the return structure is explicitly described, making this complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates. It explains `repository` with examples ('library/alpine' or 'myorg/myimage') and `limit` with default (100), minimum (>=1), and pagination cap (50 pages). This is more detail than a typical schema would provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'List tags on a Docker Hub repository with Hub-specific metadata.' It clearly distinguishes itself from the sibling tool `registry_tags` by stating it provides richer per-tag data via the Hub UI API. This leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool vs alternatives: it is for richer data than `registry_tags`, and for private repos it explicitly says to use `registry_tags` against registry-1.docker.io with credentials. It also notes 'Public repos only' and behavior for private repos (404/401). This is excellent guidance.
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 is a treasure trove of behavioral details beyond the minimal annotations: it reveals that `from_url`/`from_image` are fetched by the daemon while `from_file`/`data` are local, details error conditions (ValueError, FileNotFoundError, daemon refusing digest refs), and explains the resulting image's empty config and lack of provenance labels. It also clarifies the shell form vs exec form behavior for `changes`. Annotations only state readOnlyHint:false and destructiveHint:false, which the description aligns with and enriches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place. The description leads with a clear summary, then layers in critical caveats (distinction from image_load, empty config, single source requirement). It uses a clear 'args:' structure, bullet-like formatting for parameters, and a 'returns' line, making dense technical content scannable. Despite its length, it wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 7 parameters, no required fields, multiple source options, and subtle error semantics, this description is remarkably complete. It covers parameter validation, client-vs-daemon execution, return format, and even common pitfalls (the daemon silently substituting 'latest' for blank tags). The output schema exists, but the description still explains the return format, ensuring nothing is left to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only names and types (0% description coverage), so the description must do all the semantic work. It delivers with a dedicated 'args:' block covering all 7 parameters, including examples, defaults, error cases, and mutual exclusions. For instance, it explains that `repository` can include a tag, that `tag` overrides a tag in `repository`, and that `data` is base64-encoded by MCP. This far exceeds compensating for the schema's silence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb-resource pair ('Create an image from a flat root-filesystem tarball, like `docker import`') and immediately differentiates from the sibling `image_load` by contrasting the archive types and use cases. Distinct from the name alone and highly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly outlines when to use this tool vs. `image_load`: 'prefer `image_load` for anything `image_save` produced. Use this for a rootfs that came from somewhere else'. Provides clear scenarios (container_export archive, distro base tarball, VM image dump) and even mentions the `changes` parameter for setting a default command. This is exemplary guidance.
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 goes well beyond annotations (readOnlyHint/destructiveHint) by detailing exact output fields (config, size, RootFS.Layers, RepoTags/RepoDigests), the local-only constraint, and equivalence to docker inspect. This is valuable context for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loading the purpose, followed by details and usage alternatives, ending with args/returns. Every sentence adds value; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately explains the return value as a dict equivalent to docker inspect and lists the key fields. It also covers all necessary usage context, making it complete for a single-parameter read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a string parameter with zero description coverage, but the description fully compensates by explaining id_or_name as an image name (with optional tag/digest) or an id. This is clear and complete despite the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full inspect detail for a single local image. It explicitly distinguishes itself from siblings like image_list (quick overview), image_history (build history), and image_registry_data/registry_manifest (remote manifests).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: use image_list for quick overviews, image_history for build history, and registry tools for remote manifests. It also clarifies the tool only works on local images, giving clear when-to-use vs when-not-to-use context.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it mentions dangling build leftovers, the return payload structure, and that image_inspect is the way to get full details, going beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear purpose statement, usage alternatives, an args section, and a returns section. Every sentence is informative and no words are wasted, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, lack of output schema, and presence of annotations, this description covers all necessary aspects: purpose, scope, alternatives, parameters, and return value. It is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero description coverage, so the description fully compensates by documenting each parameter: repository, all, and filters, including what they do and the expected type of filters. It also explains the return value format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists images in the daemon's local store, with a specific verb and resource. It distinguishes itself from sibling tools by noting that registry contents are handled by registry_tags/hub_tags and image_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool vs alternatives: 'Local only — for a registry's contents use registry_tags / hub_tags, and image_search to find images on Docker Hub.' Also provides a specific filter example for dangling images.
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 goes far beyond annotations by disclosing that archives retain layers/tags/metadata, file writes are done by the server's user, `~` expansion, refusal to overwrite unless `overwrite=True`, in-band byte cap due to MCP base64 encoding, and the fallback rationale. Annotations are consistent (readOnlyHint=false, destructiveHint=false) with no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with an overview, then mode-specific details, then a parameter list. Every sentence adds meaningful information, and the content is front-loaded with the core purpose before diving into technical nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two modes, five parameters, and a compound return type, the description is complete. It explains both output shapes (bytes or dict), the byte cap, permissions, overwrite behavior, and the rationale for in-band mode. The existence of an output schema and this description together leave no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though the input schema has no descriptions (0% coverage), the description's 'args' section clearly explains all five parameters: id_or_name, dest_path, named, overwrite, and max_bytes, including defaults and behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Save') and resource ('image as a tar archive'), and explicitly distinguishes from the sibling tool `container_export` which flattens a container's filesystem. This makes the purpose unambiguous and differentiates it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains when to use `dest_path` (streaming to disk) vs in-band (fallback when no writable host path), and explicitly contrasts itself with `container_export`. It also notes the purpose (`image_load` restore), giving clear usage context.
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 annotations only indicate `readOnlyHint: false` and `destructiveHint: false`, which are minimal. The description adds substantial behavioral context: the container remains running with other attachments, only the specified endpoint is removed, networks with connected containers cannot be deleted, and force clears stale endpoints. It also states the return value. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then provides a concise behavioral note, a usage precondition, and a clearly formatted args/returns section. Every sentence adds value; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool, the description covers purpose, side effects, preconditions, parameter semantics, and return type (bool). The presence of an output schema for the return value is complemented by the explicit 'returns: bool' line. It is fully self-contained and sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It explicitly documents all three parameters: id_or_name (network id/name), container (container id/name), and force (with its purpose). This adds meaning beyond the bare schema types and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb+resource: 'Disconnect a container from a network.' It clearly distinguishes itself from siblings by defining the exact scope: only the endpoint is removed while the container keeps running. It also references `network_connect` and `network_remove`, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: the description states this is the reverse of `network_connect`, and that it must be used before `network_remove` when a network has connected containers. It also explains when to use `force` (to clear stale endpoints from deleted containers). This gives the agent clear decision rules among related tools.
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?
While annotations already declare destructive and idempotent behavior, the description adds crucial context: built-in networks are never removed and only networks with zero connected containers are eligible. It also documents the return dict, going beyond the bare annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct paragraphs: the first states purpose, eligibility, and safety; the second documents args and return. No redundancy or filler, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one loosely-typed parameter and no output schema, the description covers purpose, usage conditions, filter semantics, alternative tool, and return format. It is entirely sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining the 'filters' parameter: valid keys 'until' and 'label' with formats, and that omitting it removes all unused custom networks. This is far more than the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove networks that have no active container endpoints' – a specific verb, resource, and condition. It also distinguishes itself from network_remove by explicitly noting the alternative for single-network deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use: 'Only networks with zero connected containers are eligible' and clearly names the alternative: 'Use network_remove to delete one specific network instead.' It also specifies built-in networks are never removed, providing clear boundaries.
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?
Annotations indicate destructive behavior, but the description adds actionable details: fails if containers are attached, built-in networks always error, and returns True after removal. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, front-loading purpose and following with failure modes, alternatives, and parameter/return details. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers purpose, failure scenarios, alternatives, parameter meaning, and return value. It is fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by explaining id_or_name as 'The network id or name'. This directly adds meaning beyond the raw schema, which only specifies type string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Remove') and resource ('a single custom network by id or name'). It distinguishes from sibling tools like network_prune and network_disconnect, making the scope explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: when to use (single custom network), failure conditions (attached containers must be disconnected), built-in network restrictions, and an alternative for bulk cleanup (network_prune). Clearly differentiates from related tools.
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?
Annotations only declare readOnlyHint and destructiveHint, but the description adds crucial behavioral details: it never raises on timeout, always returns met and timed_out, polls at poll_interval, and caps poll_interval by remaining time so a large value cannot exceed timeout. These details inform the agent of failure modes and timing semantics not present 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Though longer than typical descriptions, every sentence is load-bearing: core blocking behavior, timeout semantics, common use cases, task-tracking caveat, parameter list, and return shape. The structure is well-organized with paragraphs and an args block, front-loaded with the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description's explicit return-field list (node, until, met, timed_out, state, availability, waited_seconds) is essential. Combined with full parameter semantics, timeout/polling behavior, and caveats about task placement, the description is complete for a wait-type tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully compensates by explaining each parameter: id_or_name, until (with allowed states), timeout_seconds (default 300), and poll_interval (default 2, >0, capped). It adds meaning beyond the schema's bare type and enum definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence precisely states the verb, resource, and target: 'Block until a swarm node's Status.State reaches a target value.' It further distinguishes itself from sibling tools by naming what it does not do (task placement tracking) and pointing to alternatives like service_wait and node_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases are provided ('until="ready"' after a newly joined node, 'until="down"' while draining a node before removal). The description also states clear exclusions: it does not track task placement, and for that check the agent should inspect services' tasks directly, with service_wait and node_list named as relevant alternatives.
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?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses crucial behaviors: the plugin is created disabled, errors are raised for missing directories or duplicate names, no provenance labels are stamped, and plugin_data_dir is read client-side (not on the daemon host). These details are not inferable from annotations and materially affect tool usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a crisp purpose sentence, followed by a compact but dense paragraph of behavioral context, and then a clean args/returns section. Every sentence adds value—no filler, redundancy, or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and sparse parameter descriptions, the description carries the full burden. It includes the return dict fields, preconditions, error conditions, lifecycle steps, and the distinction from the sibling plugin_install tool. This is as complete as an agent needs for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully compensates. It explains the name format (`author/name:tag` with optional `:latest`), specifies that plugin_data_dir must contain config.json and rootfs and is read on the server's filesystem, and clarifies gzip's role and default. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('Build') and resource ('plugin from a local plugin data directory and install it under name'). It explicitly distinguishes this from plugin_install, which pulls an already-published plugin from a registry, making it clear among sibling plugin tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: use this only for a self-built rootfs, use plugin_install for anything on a registry. It also provides prerequisites (config.json and rootfs required), container bind-mount requirement, and a clear lifecycle sequence: plugin_configure then plugin_enable.
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?
Description adds substantial behavioral context beyond the readOnlyHint/destructiveHint annotations: it reads remote plugin data without installing, may raise on unresolved references, relies on credentials from system_login or ~/.docker/config.json, and explains the security significance of host-level privileges. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Despite its length, every sentence earns its place. The description is front-loaded with purpose, uses structured 'args' and 'returns' sections, and avoids redundancy. It's detailed but not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fully complete for a tool with one parameter and no output schema: it covers return format with examples, error behavior, authentication, and use-case context. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'remote' is fully explained with format ('author/name:tag'), optional ':latest' default, and return structure. Schema coverage is 0%, so the description completely compensates, leaving no ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Ask the registry which host privileges a not-yet-installed plugin demands.' It distinguishes itself from sibling tools by explicitly specializing in uninstalled plugins and contrasts with plugin_inspect for installed plugins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'The review step before plugin_install' and warns of non-interactive grants. It also names the alternative for installed plugins: 'read Config from plugin_inspect instead.' This is clear, actionable, and specific.
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?
Beyond annotations (destructiveHint=true, readOnlyHint=false), the description adds key behavioral details: permanent removal, the requirement to disable before removal unless force=True, and that plugin names come from plugin_list. This fully discloses the operational scope and consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using clear sections for behavior, args, and returns. Every sentence provides necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 0% schema parameter coverage, the description covers purpose, usage, parameters, and return value, while also referencing plugin_list and plugin_disable for context. It is fully complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining both parameters: name (plugin name with example) and force (remove even if enabled, default False). It also documents the return value (bool), providing complete parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uninstalls an engine plugin from the daemon, using a specific verb and resource. It further distinguishes itself from plugin_disable by noting permanent removal, which fully differentiates it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool vs the alternative: 'to deactivate but keep a plugin installed use plugin_disable instead.' It also covers the prerequisite that an enabled plugin must be disabled first unless force=True, providing clear usage context.
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?
Beyond the readOnlyHint annotation, it discloses that the response may be a single-platform manifest or multi-platform list depending on the registry's tag, and explains that `repository` strips `:tag`/`@digest`, which is a non-obvious behavior. Also details credential overriding without config.json support. This is substantial added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence is informative: core action, response variability, transport mechanism, alternatives, parameter doc, and return structure. It is front-loaded with the essential purpose and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description explicitly defines the return dict keys ('name', 'registry', 'reference', 'media_type', 'digest', 'manifest'). The combination of parameter details, alternatives, and response shape makes it self-sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions, but the description provides full parameter semantics: `repository` with example and tag-stripping note, `reference` with default, `username`/`password` with override behavior. This completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the primary function: 'Fetch a repository's manifest without pulling.' It goes further to explain the possible response types (single-platform vs multi-platform list) and explicitly names alternative tools, making its purpose unambiguous and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly addresses when to use this tool by presenting alternatives: `buildx_imagetools_inspect` (uses docker CLI and credential store) and `image_registry_data` (asks the daemon). This gives the agent a clear decision framework. Also notes 'Talks HTTPS directly — no daemon or CLI needed' to justify its suitability.
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?
Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context: it bypasses ~/.docker/config.json, supports anonymous access, strips tag/digest from repository input, caps pagination at 50 pages, and includes a truncated flag in the return. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. It front-loads the primary purpose, uses a clear args: section, and every sentence contributes meaningful detail. No filler or repetition of schema/annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description documents the return dict structure (name, registry, tags, truncated). It addresses auth behavior, registry support, pagination limits, and input normalization, making it complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero descriptions for any of the 4 parameters, but the description compensates fully with an 'args:' block explaining each: repository format (e.g. alpine, ghcr.io/org/repo), username/password overrides, and limit default with pagination cap. This is complete semantic coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'List tags for a repository in an OCI v2 registry without pulling.' It clearly distinguishes itself from sibling tools like registry_manifest (fetch one tag's manifest) and hub_tags (Hub-specific tag metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context for various registries (Docker Hub, GHCR, ECR, GAR), and points to alternatives: 'Fetch one tag's manifest with registry_manifest; hub_tags adds Hub-specific tag metadata.' Also gives guidance on auth for private registries, explaining why env vars are preferred over args.
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?
Beyond the readOnlyHint/destructiveHint annotations, the description discloses critical behavior: it never raises on timeout, polls registry_tags at a configurable interval, and has a pagination limitation that can cause tags to be missed. It also notes that repository :tag/@digest suffixes are stripped, which is non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, a caveat paragraph, and a parameter list. Every sentence adds value, and the most important purpose is front-loaded. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter polling tool with no output schema, the description covers purpose, behavior, parameter semantics, return value shape, and a critical edge case. It is fully self-contained and leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes a detailed args section that explains each of the 7 parameters, including defaults, constraints, and forwarding behavior (e.g., limit forwarded to registry_tags). This fully compensates for the input schema having zero descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool blocks until a specific tag appears in a repository, with a concrete example of waiting for a CI push to land. It also distinguishes itself from other wait tools by explicitly noting the lack of a host argument and its registry-specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by stating it works against Docker Hub too (so no separate Hub variant) and contrasts with other wait tools. It also advises raising the limit for very large tag lists, helping the agent decide when and how to configure the tool.
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?
Beyond the readOnly and destructive annotations, the description discloses failure modes (does not raise on non-zero exit, raises on missing plugin, raises ValueError for remote host with local path) and explains the return dict structure, adding significant transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with purpose, then usage, error conditions, parameter list, and return format. Each sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, complex constraints, and no output schema, the description is complete. It covers all parameters, constraint rules, error cases, and return format, making it fully informative for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, constraints, and defaults. It also clarifies the format parameter's parsing behavior and the to/to_env/to_latest exclusivity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two image references and reports the CVE delta, using specific verb and resource. It also distinguishes from the sibling scout_cves, which scans a single image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after a rebuild) and contrasts with scout_cves. Also specifies the exact one-of requirement for to/to_env/to_latest and notes error behaviors like non-zero exit handling and remote host limitations.
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?
Annotations already mark the tool as read-only and non-destructive, but the description adds substantial behavioral context: authentication prerequisites, platform-specific host login needs, format-dependent result encoding, and the non-zero exit behavior (only missing plugin raises, otherwise inspect raw.stderr). This goes well beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It covers purpose, usage alternatives, auth prerequisites, error behavior, and all parameters in a well-organized structure with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the return dict structure (format, result, raw) and how result varies by format. It also covers error handling and authentication context. For a tool with 6 parameters and no output schema, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 fully compensates by explaining each parameter's meaning. It clarifies format semantics (no plain 'json', some formats parsed into result, some returned verbatim), only_fixed, ignore_base, only_severity, and platform. This adds meaning that the bare schema names and enums do not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List vulnerabilities (CVEs) in an image via Docker Scout.' It also explicitly distinguishes itself from sibling tools by pointing to scout_quickview for summaries and scout_sbom for package inventory without vulnerability matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: anonymous scans for public images, docker login requirements for policy enforcement, and clear alternatives ('Start with scout_quickview...; scout_sbom inventories...'). It also warns about exit-code behavior and when to inspect raw.stderr.
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?
Beyond the annotations, the description discloses critical behaviors: the payload can never be read back, cannot be changed, and requires keeping a local copy. It also mentions provenance labels, providing useful context not captured by structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise intro, a focused behavioral note, an args list, and a returns line. Every sentence adds value, and the structure makes the information easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description covers prerequisites, return format, constraints, and alternatives. It fully explains the write-once limitation and rotation strategy, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining every parameter: name (unique within swarm), data (max 500 KB, must be empty when driver set), labels, and driver (external store config). This adds meaning the schema alone lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: 'Create a swarm secret' and adds the prerequisite 'requires a swarm manager.' It also distinguishes this tool from config_create, making it easy to differentiate from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'For non-sensitive data that should stay readable, use config_create instead.' It also instructs on write-once semantics and rotation, giving clear context for when this tool is appropriate.
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?
Beyond the readOnlyHint/destructiveHint annotations, the description discloses that `Spec.Data` is write-only and never returned, and that there is no server-side filter for services using the secret. This adds meaningful behavioral context that annotations do not capture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence summary, followed by a necessary caveat and focused usage guidance. The args/returns block is compact, and every sentence adds substantive information without digression.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter readonly inspection tool, the description covers what is returned, what is excluded, the operational prerequisite, and the relevant alternative approach. Even without an output schema, the description is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter with no description, but the description includes 'args: id_or_name - The secret id or name', fully explaining the parameter. It also clarifies that both ID and name are accepted, which is valuable semantic information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a swarm secret's metadata by id or name', which is a specific verb, resource, and scope. It clearly differentiates from sibling tools like secret_create, secret_list, and secret_remove by focusing on inspection of metadata rather than creation, listing, or removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool ('check CreatedAt, Labels, or which driver created it') and when not to use it ('not to read its contents'). It also names the alternative `service_inspect` for finding services that reference a secret, and notes the prerequisite of a swarm manager.
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?
Beyond annotations (readOnlyHint=true, destructiveHint=false), the description adds meaningful behavioral context: it notes that one entry per service represents the desired state (not the actual tasks), and explains the `managed_only` label behavior. This enriches the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently organized with an initial one-line summary, then detailed args and returns in a clear format. Every sentence contributes necessary information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite minimal schema and no output schema, the description covers prerequisites, alternatives, parameter semantics, and return format (list of full service documents), making it sufficient for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by explaining both `filters` (attributes id, name, label, mode) and `managed_only` (filters on docker-mcp-server.managed label, combines with other filters). This adds meaning well beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List swarm services' with a specific verb and resource. It explicitly distinguishes from siblings by mentioning `service_ps` for tasks and `stack_services` for grouping by stack, so the agent knows exactly what this tool does relative to others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit prerequisite ('Must run against a swarm manager') and names alternatives (`service_ps` and `stack_services`) for different use cases, giving clear when-to-use versus when-not-to-use guidance.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds meaningful behavioral context by explaining what the tasks reveal ('Shows where replicas run and why they fail'), detailing the fields in each task, and noting the swarm manager requirement. This goes well beyond the safety annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then provides layered detail in a well-structured format (args/returns). Every sentence contributes value: the Docker CLI analogy, the failure-analysis context, alternatives, prerequisites, and parameter documentation. No filler or repetition exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description specifies the return structure: 'list - Task dicts (ID, Slot, NodeID, Status, DesiredState, Spec).' It also explains the significance of the data and how this tool relates to other service inspection methods. Given the tool's moderate complexity, this description is fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry parameter documentation. It fully does: 'id_or_name - The service id or name' and 'filters - Filter dict; keys: id, name, node, label, desired-state (running|shutdown|accepted).' This provides types, allowed keys, and enum-like values directly in the description, compensating completely for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List a swarm service's tasks (per-replica scheduling units), like `docker service ps`.' It clearly differentiates from siblings by mentioning `container_list`, `stack_ps`, and the `service-tasks://` resource, making the tool's unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Prefer this over `container_list` for services (tasks may run on other nodes), `stack_ps` for a whole stack, and the `service-tasks://{id_or_name}` resource for a computed rollout summary.' It also states the prerequisite 'Requires a swarm manager,' giving clear when-to-use and alternative context.
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?
Annotations only indicate readOnlyHint=false and destructiveHint=false, which are minimal. The description adds crucial behavior: the call returns once the update is accepted, not when tasks are running, and scaling is asynchronous. It also clarifies mode restrictions. This goes well beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-line purpose, then context paragraphs, then a concise args list. Every sentence provides necessary information—mode restriction, async behavior, alternatives, and return value—without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no nested objects), and the description covers all essential context: what it does, when to use it, async behavior, return type, and how to verify progress. The output schema exists and is supplemented by the 'returns: bool' line. This is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates with an explicit args section: 'id_or_name - The service id or name' and 'replicas - The desired number of running task replicas.' This adds meaningful semantic explanation beyond the raw schema, which only lists types and required status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Set the desired replica count for a Replicated-mode swarm service.' It clearly identifies the operation and differentiates from siblings by mentioning 'Replicated-mode' and noting that Global services have no replica count. This prevents confusion with service_update or other service tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (Replicated-mode services), when not to use it (Global services), and provides an alternative for other spec changes ('use service_update instead'). It also advises checking progress via service_ps or service_inspect. This is exemplary usage guidance.
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?
Beyond the readOnlyHint/destructiveHint annotations, the description discloses that output is parsed from CLI `--format '{{json .}}'`, that a RuntimeError is raised on CLI failure, and that results include error details. This adds meaningful behavioral context not available from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence summary, an args section, and a returns section. Every sentence adds value, and the text is compact without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description covers the return type (list of dicts with fields), all parameter meanings, error behavior, and the swarm manager prerequisite. This makes it self-sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description provides detailed semantics for all three parameters: `name` identifies the stack, `no_trunc` controls truncation, and `filters` includes an example and explains list-value behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List the tasks of a stack' with a clear verb and resource, and explicitly contrasts with `service_ps` to clarify scope. It differentiates itself as the task-level view across every service.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names `service_ps` as an alternative for one-service coverage, and notes the swarm manager requirement. This gives clear context for when to use this tool versus alternatives.
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?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds meaningful behavioral traits: it raises RuntimeError on CLI failure, requires a swarm manager, and describes the parsing method and output format. This goes beyond the annotation baseline and provides useful operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and well-structured. It front-loads the core purpose in the first sentence, then provides alternatives, prerequisites, error behavior, and parameter details in a compact format. Every sentence and section contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description specifies the return type and shape: 'list - One dict per service (id, name, mode, replicas, image, ports)'. It covers all necessary context for a simple list tool, including filtering syntax and the distinction from sibling tools, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage, but the description compensates fully by explaining both parameters: 'name - The stack to list services for' and 'filters - Filter by attributes, e.g. {"name": "web"}; a list value repeats the filter'. This adds concrete semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List the services of a stack'. It specifies the verb 'list' and resource 'services of a stack', and distinguishes it from related siblings by noting that `stack_ps` is for individual tasks and `service_inspect` for full spec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use this tool versus alternatives is provided: 'use `stack_ps` for individual tasks and `service_inspect` for one service's full spec'. It also states the prerequisite 'Requires a swarm manager', giving clear context for usage.
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 discloses critical behavior such as failure when already in a swarm, the one-time display of the unlock key after enabling autolock, and the force_new_cluster disaster recovery option. It also explains advertise_addr requirements, which goes beyond the minimal annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a general intro followed by an arg list. While detailed, every sentence adds value, from failure conditions to parameter explanations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no schema descriptions, and a complex domain, the description covers initialization workflow, prerequisites, parameter meanings, return value, and important caveats, making it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema having 0% description coverage, the description includes a dedicated 'args:' section that explains all 11 parameters with meaningful details, such as 'advertise_addr - Externally reachable address advertised to other nodes' and 'force_new_cluster - Force a new single-node cluster...'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Initialize a new swarm, making this Engine its first manager node,' which clearly states the action and scope. It distinguishes itself from sibling tools like swarm_join and swarm_leave by describing the initialization role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly warns 'Fails if the Engine is already part of a swarm — call swarm_leave first' and instructs using swarm_join_tokens and swarm_join for additional nodes. This provides clear when-to-use and alternatives.
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?
Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behaviors: it fails if already in a swarm, the role is entirely token-dependent, advertise_addr is auto-detected under certain conditions and must be reachable by all nodes, and it returns a boolean. This adds substantial transparency about failure modes and networking requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a purpose statement, behavioral details, and a clean args list. Every sentence adds necessary information, including the failure condition and auto-detection nuance. It is appropriately sized for the complexity of the operation without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (swarm networking) and an output schema (bool) which is mentioned in the description. The description covers all parameters, failure modes, and return value. It also references related tools (swarm_join_tokens) for context. Nothing critical appears missing for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero parameter descriptions, but the 'args:' section fully explains each parameter's purpose: remote_addrs, join_token, listen_addr, advertise_addr, and data_path_addr. It also elaborates on join_token's role-determining semantics and advertise_addr's auto-detection behavior, going well beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Join this Engine to an existing swarm as a worker or manager.' It uses a specific verb+resource and distinguishes from siblings like swarm_init (which creates a new swarm) by explicitly referencing 'existing swarm.' The role (worker/manager) is also clarified as determined by the token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-not guidance: 'Fails if the Engine is already part of a swarm.' It also explains the prerequisite of obtaining tokens from swarm_join_tokens, indicating proper context. While it doesn't name alternatives like swarm_init, the failure condition and existing-swarm context provide clear usage boundaries.
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?
Beyond the annotations readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: it is read-only, requires a swarm manager, and raises `docker.errors.APIError` when the task does not exist, when a prefix is ambiguous, or when the node is not a manager. It also explains the daemon's resolution order for ids and names. No contradiction 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear paragraphs and explicit `args` / `returns` sections. It is long but every sentence provides actionable guidance or necessary caveats, with no wasted repetition. The clarity and structure enable accurate tool invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one simple string parameter, no output schema, and the subtle Docker swarm name-resolution behavior, the description is thorough enough to support correct invocation. It covers the single-task purpose, return payload shape, required manager authority, error conditions, and caveats about accessing the underlying container across nodes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 0%, the description fully compensates by thoroughly explaining `id_or_name`: it covers valid id prefixes, full name form `<service>.<slot>.<taskid>`, the global-service variant, the trap that `docker service ps` NAME column does not resolve, and the daemon's fallback order plus ambiguity rejection. This is far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects a single swarm task, using the docker CLI analogy `docker inspect --type task` and explicitly distinguishes it from `swarm_task_list` as the single-object fetch. The verb-resource pairing is unambiguous and differentiates from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: when the agent already holds a task reference and wants only that task. It also names alternatives and exclusions: prefer `swarm_task_list` when scanning, use `container_inspect`/`container_logs` to reach containers with caveats, and use `service_logs` for cross-task logs. It additionally states the prerequisite of a swarm manager.
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?
Beyond the annotations (readOnlyHint, destructiveHint), the description adds critical behavioral details: it is read-only, requires a swarm manager, and raises an error on non-manager nodes. It also notes that each task contains its full spec, which affects output size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with a one-line summary, then usage comparisons, filter details, and return information. It packs substantial information without redundancy and remains clear and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the minimal schema and no output schema, the description provides a complete picture: purpose, usage, parameter semantics, return shape, error conditions, and prerequisites. It leaves no significant gaps for an AI agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only provides a filter object without documentation, but the description thoroughly explains all valid filter keys (id, name, service, node, label, desired-state) and the possible values for desired-state. This fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tasks across the entire swarm, and uses an analogy to `docker service ps` to make the purpose instantly understandable. It also distinguishes it from related tools like `service_ps` and `stack_ps`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (for cluster-wide task listing) versus the alternatives (service-scoped, stack-scoped). It also details how filters can narrow down results, providing concrete usage guidance.
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?
Beyond annotations, it discloses important side effects: 'Token rotation invalidates the old join token immediately' and 'Rotating the unlock key requires all managers to be re-unlocked on restart.' It also clarifies that existing joined nodes are unaffected. This is rich behavioral context that annotations (which only say readOnlyHint false, destructiveHint false) do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized, front-loaded with purpose, then usage constraints, then side effects, then params and return value. Every sentence earns its place; no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no required params, no robust schema descriptions, and no output schema, the description covers all necessary aspects: prerequisites, effects, related tools, param explanations, and return type. It is complete for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter: 'rotate_worker_token - Issue a new worker join token, invalidating the current one' and similarly for others. This adds meaning beyond the bare boolean names and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Update swarm-wide settings' with a specific scope: 'the single home for join-token and unlock-key rotation.' It distinguishes itself from siblings like swarm_join_tokens and swarm_unlock_key by being the update/rotation counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Must be called on a swarm manager node') and provides complementary guidance: 'Use swarm_join_tokens to retrieve the new tokens after rotation' and 'retrieve it immediately via swarm_unlock_key.' This clearly maps to sibling tools for retrieval, setting expectations for the correct workflow.
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 goes well beyond annotations, detailing that there is no true logout, the daemon is not contacted, host config is untouched, the private docker-py attribute is accessed, and it degrades gracefully. This gives the agent accurate expectations for side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence adds value—key facts are front-loaded, and technical caveats are organized in a clear paragraph. The args/returns block makes it scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple schema and no output schema, the description covers the operation's behavior, return value, edge cases, and internal implementation notes. It is fully self-contained and leaves no important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description fully documents the single 'registry' parameter, including its meaning, default (None = all), and the Docker Hub key name ('docker.io'). This is far more than the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Clear cached registry credentials from this server's in-memory Docker client.' It clearly distinguishes itself from siblings like system_login, system_close, and system_reconnect by explaining it only clears the in-memory cache and doesn't contact the daemon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: to clear cached credentials, and names alternatives (system_login, system_close, system_reconnect) that also clear it. It explains the difference between clearing all vs a specific entry and the key matching requirement, giving the agent clear decision criteria.
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?
Annotations already say readOnlyHint=true and destructiveHint=false, but the description goes further: "Read-only, never raises on a query matching nothing, and always registered even when DOCKER_MCP_SERVER_DISABLE drops every domain." It also discloses that rows are summaries, not definitions, and how `hidden_by_configuration` works. This adds behavioral context well beyond the structural hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence summary, then structured into args and returns sections. It is dense but every sentence adds value, covering edge cases, comparisons, and return structure without redundancy. Length is justified by the tool's complexity and 3 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description provides a detailed returns dict: "{matched, tools, domains, no_domain, hidden_by_configuration, switches, filters}" and explains key semantics like `domains` keys and `no_domain`. It also covers configuration-related behavior and definitive negative matches, making the tool fully self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description's `args:` block fully compensates: "domain - Exact domain name (see any result's `domains` key); omit for every domain,” plus category and keyword semantics. It explains categorical enum values and how omission behaves, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "List this server's registered tools as compact rows, filtered by domain, category or keyword." It clearly distinguishes itself from siblings by positioning as a mirror of the MCP resource and noting "docs_lookup covers external Docker reference documentation." The scope ('this server's own surface') and unique abilities (e.g., filtering by destructive category) make its 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 Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage scenarios are provided: "Use it to brief on an unfamiliar area (`domain="buildx"`)... to check blast radius (`category="destructive"`), or to establish that nothing matches." It contrasts with `docs_lookup` for external docs and clarifies that dropped/disabled tools are absent rather than flagged. These are clear when-to-use and when-not-to-use guidelines with named alternatives.
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?
While annotations indicate the tool is not read-only and not destructive, the description adds significant behavioral context: the lifecycle differences between named and anonymous volumes, the '--rm' and 'docker rm -v' removal caveat, and the fact that volumes are 'stamped with provenance labels.' These details are not available in the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every sentence provides necessary information: use cases, lifecycle caveats, driver option examples, related tools, and return format. It is well-structured in paragraphs and not repetitive, earning its length without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested objects, no output schema), the description is complete. It covers purpose, parameter semantics, driver options, lifecycle behaviors, related tools, and return value shape. The agent has everything needed to invoke the tool correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining each parameter in context: 'name' determines anonymous vs. named volume, 'driver' defaults to 'local', and 'driver_opts' includes concrete examples for bind mounts and NFS. It also documents the return value structure, which is not in an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear, specific statement: 'Create a volume managed by Docker.' It distinguishes this from related volume tools by explaining when anonymous vs. named volumes are appropriate, making the purpose unambiguous and distinct from volume_list, volume_prune, and volume_remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states use cases: 'use them for databases, uploads, or any data that must outlive a container.' It also provides alternative actions: 'List existing volumes with volume_list; reclaim unused ones with volume_prune.' This goes beyond a simple usage hint and tells the agent when to use this tool versus related operations.
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?
Beyond the annotations (destructiveHint=true), the description discloses critical behavior: it fails if any container references the volume, force=True lets removal proceed but containers lose underlying data, and it returns a bool. This adds significant context beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written with a clear structure: purpose, failure behavior, alternative, and then a structured args/returns section. Every sentence contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with annotations and an output schema, the description covers all essential aspects: what it does, failure modes, force behavior, the alternative tool, parameter meanings, and return type. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the schema has no parameter descriptions (0% coverage), the description fully compensates by explaining both parameters: 'name' as the volume name and 'force' as permitting removal despite container references. This is complete semantic coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a single volume by name,' which is a specific verb+resource statement that clearly distinguishes it from other volume tools. It also contrasts with volume_prune by noting bulk cleanup, cementing the differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool versus the alternative: 'For bulk cleanup of volumes with no container references at all, use volume_prune instead.' It also describes the failure condition when containers reference the volume, giving clear context for when force is appropriate.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/L337-org/docker-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server