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

Over and above the annotations, it discloses a key behavioral twist: non-zero CLI exits do NOT raise, while a missing plugin or timeout DOES raise, and the agent should inspect `returncode`/`stderr`. It also adds the real-world nuance that `cwd` is copied to the target host when no local plugin is present. These are non-obvious behaviors that materially affect how an agent interprets results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly organized: purpose, usage decision, exception/return behavior, parameter list, and return structure. Each line earns its place; there is no filler or repetition of what the schema already shows without added value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with no output schema, this description is thorough: it documents the args array, the return dict shape, default values, and atypical exit behavior. It gives an agent everything needed to invoke it correctly and interpret results confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries the full burden for all 10 parameters. It covers each parameter with meaningful prose: `targets` default, `files` manual repeatability, `set_overrides` with an inline example, `cwd` copy behavior, and `timeout_seconds` default. This is excellent compensation for the sparse schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Build multiple targets defined in a bake file (HCL, JSON, or compose).' It also explicitly differentiates from the single-target sibling (`buildx_build`), so an agent can immediately tell which tool is for which job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the tool ('Use it for multi-target builds declared in docker-bake.hcl/compose files') and when not to, directing single Dockerfile targets to `buildx_build`. This is clear, actionable, and leaves little room for misinterpretation.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals that it always runs with --progress=plain, copies local context to remote hosts when no local plugin exists, and raises ToolInputError in specific remote scenarios. It also states that non-zero CLI exits do not raise but returncode/stderr should be inspected. This gives the agent a thorough understanding of side effects, error conditions, and edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but highly structured: a one-line summary, differentiation from the legacy tool, key behavioral notes, and then parameter explanations. Every sentence carries actionable information; there is no fluff or repetition. The use of headings and clear formatting makes the length appropriate for a tool with 24 parameters and complex remote execution semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, usage, constraints, error behavior, remote execution details, and returns an explicit return format (dict with returncode/stdout/stderr/truncated). It addresses pitfalls (e.g., stdin blocking, path expansion, remote-side resolution) and provides enough detail for an agent to invoke the tool successfully in any scenario. No gaps are apparent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries the full burden of documenting all 24 parameters. It provides a detailed Args section with explanations for each parameter, including examples and critical caveats (e.g., context not supporting stdin tarballs, relative Dockerfile path resolution, timeouts). This fully compensates for the empty schema and adds value beyond anything the schema could provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise action: 'Build an image with BuildKit via docker buildx build.' It then explicitly differentiates itself from the sibling `image_build` tool by listing the specific features it supports (multi-platform, cache export, attestations, secrets, multi-stage). This makes the tool's purpose unmistakable and distinguishes it from alternatives without needing to inspect schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool instead of `image_build` (for multi-platform, cache_from/cache_to, SBOM/provenance, secrets, target). It also explains the behavioral difference when a remote host is involved and lists conditions that raise ToolInputError. Clear guidance on when to use and what to expect, with no ambiguity.

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

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

Goes well beyond the generic annotations by disclosing error semantics: non-zero CLI exits do not raise, but a missing buildx plugin or timeout does, so callers must inspect returncode/stderr. It also clarifies side-effect behaviors like bootstrap timing, use-as-default, config copying, and append semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a purpose/usage paragraph, an Args list, and a Returns block. It is detailed but every sentence adds functional value; nothing is redundant with the schema, and the most important usage context is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 9 parameters, no output schema, and sparse annotations, but the description fully compensates: it documents all parameter semantics, return shape, exception behavior, version requirements, and common invocation patterns. An agent has everything needed to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries the full burden for all 9 parameters, and it succeeds. Every parameter gets a meaningful explanation, including examples like driver values, driver_opts conversion to --driver-opt, the buildx >= 0.17 constraint for config, and the multi-node intent of node_name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Create a new BuildKit builder instance,' which is a specific verb+resource statement. It further differentiates from siblings by indicating this is the setup step before buildx_build and the counterpart to buildx_use for switching builders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when it is needed: when the default docker driver falls short for multi-platform builds and cache export. It also gives clear routing guidance: use=True makes it the default for later buildx_build calls, otherwise switch with buildx_use, and bootstrap=True starts the builder immediately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context: it can drop the final partial record when output exceeds MAX_CLI_OUTPUT_BYTES, and it raises RemoteFailureError on CLI failure. These are not implied by annotations and help an agent anticipate failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, followed by necessary caveats (truncation), remediation (run on host), and cross-references. Each sentence earns its place, with no redundancy. The Args/Returns block is compact and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description specifies the return as a list of dicts parsed from the JSON format. It covers the truncation edge case, error behavior, and the parameter semantics. For a simple read-only reporting tool, this is complete: an agent knows what to expect, when to use alternatives, and how to handle failures.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries full responsibility for the 'builder' parameter. It explains it 'Overrides the active builder', which gives clear meaning beyond the raw name and type. It does not mention the default behavior explicitly, but 'override' implies it uses the active builder if not provided. This is adequate for a single optional parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'Report' and a precise resource 'BuildKit cache disk usage as a list of records', and distinguishes itself from related tools by noting system_df covers daemon-side disk and buildx_prune reclaims cache. Clear and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names alternatives and when to use them: 'Reclaim the cache with buildx_prune (system_df covers daemon-side disk, not builder cache)' and advises running the CLI on host directly for exhaustive accounting if output is large. Provides clear 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.

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

Goes well beyond the readOnly/destructive annotations by disclosing JSON parsing, the buildx >= v0.13 requirement, RemoteFailureError, ref normalization from qualified to bare id, and the {'raw': stdout} fallback when output is not a JSON object.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average but every sentence earns its place: purpose, prerequisites, error behavior, parameter semantics, and return format. It is front-loaded with the core purpose and uses a clear Args/Returns structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description explains the return value as a parsed dict and the raw fallback. It covers prerequisites, failure behavior, parameter semantics, and typical usage context, leaving no essential gap for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries the full parameter burden and does so thoroughly. It explains ref's qualified format, automatic reduction to bare id, builder targeting, default builder selection, and valid syntaxes like '^0'. Builder is also fully described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Inspect a single build record by ref'. It clearly distinguishes this from buildx_history_list by saying the record is found via that list, and frames the purpose as debugging failed or slow builds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes the intended use case: debugging a failed or slow build located through buildx_history_list. It also gives practical invocation guidance for ref, including empty/omitted behavior and the ^N syntax, but does not explicitly state when to prefer sibling inspect tools.

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

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

Annotations already mark the operation as read-only and non-destructive; the description adds valuable behavioral context beyond them: the exact CLI format used, the buildx version requirement, and the specific RemoteFailureError raised on CLI failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by necessary context (record contents, version requirement, error behavior), then compact Args and Returns sections. Every sentence carries useful information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the Returns section usefully describes the list shape and included record fields. It also covers error behavior and the version constraint. The only minor gap is unspecified ordering or result-size limits, but these are unlikely to block correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by documenting `builder` as 'Builder instance to read history from (defaults to the active builder)'. This adds practical meaning, though the schema's string type vs. 'Builder instance' wording creates minor ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Starts with a specific verb and resource: 'List recent build records (BuildKit build history)', plus the exact parsing method via `--format '{{json .}}'`. It also references `buildx_history_inspect` as the natural downstream tool, making its role distinct from that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly states it is useful for finding a build to drill into with `buildx_history_inspect`, and gives a version prerequisite. It does not explicitly enumerate when to favor alternatives like `buildx_list`, but the intended use case is clear.

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

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

With annotations covering only readOnlyHint=false and destructiveHint=false, the description adds significant behavioral context: it mentions the operation 'builds the index and pushes it in one operation', and importantly discloses that it 'Does not raise on a non-zero CLI exit... inspect returncode/stderr'. It also describes the dry_run flag. This exceeds the bare annotations and informs the agent about side effects and error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is organized into a compact summary, an Args list with one-line explanations, and a Returns section. It is front-loaded with the core purpose and prerequisites. Every sentence adds value—there is no filler, and the structure makes quick scanning easy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description explicitly states the return dict format and fields. It covers error behavior (non-zero exit), parameter nuances, and prerequisites. For a moderate-complexity tool with 9 parameters, this is complete—an agent has all the information needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the full burden. It lists all nine parameters with brief but meaningful explanations: target, sources, append, dry_run, annotations, platforms, descriptor_files, builder, and timeout_seconds. For example, it notes annotations are 'passed verbatim' and descriptor_files are 'copied to the target host if no local plugin'. 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise statement: 'Create a manifest list / OCI image index from existing per-platform tags.' This names the specific operation and resource, and distinguishes it from sibling buildx tools by clarifying it stitches existing tags rather than building or inspecting. It clearly differentiates from `buildx_imagetools_inspect`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states a clear prerequisite: 'Source tags must already be pushed; this only stitches them together.' It also suggests a verification step with `buildx_imagetools_inspect`. However, it does not explicitly contrast with alternatives like `buildx_build` or `image_push`, so the usage context is clear but lacks an explicit whitelist/blacklist of when not to use.

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

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

Annotations already mark it read-only/non-destructive, and the description adds important behavioral context: it does not raise on a non-zero CLI exit, but still raises on missing plugin/timeout, and it returns returncode/stderr for the caller to inspect. It also discloses credential-store usage and OCI index support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then moves through alternatives, error behavior, args, and returns. Every section earns its place, and the Args/Returns formatting makes it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only inspect tool, it covers the full call contract: what it does, how it differs from alternatives, all parameters, the return dict shape, and when stdout contains a parseable JSON document. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden. It explains all four parameters: image with concrete examples, raw with behavior, format with mutual exclusivity, and builder as an override. This is strong compensation for the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Inspect a manifest in a registry without pulling.' It clearly distinguishes itself from docker manifest inspect and registry_manifest, so an agent can tell exactly what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says it replaces docker manifest inspect, explains why, and names registry_manifest as the alternative for direct HTTPS without a daemon or plugin. This gives clear when-to-use and when-to-avoid guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond that: it discloses the tool does not raise on a non-zero CLI exit, while missing plugins or timeouts still raise, and directs the agent to inspect returncode/stderr. This is valuable exception-level transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with purpose, comparative guidance, exception behavior, Args, and Returns sections. It is front-loaded with the core purpose followed by the sibling distinction. Minor redundancy exists, such as mentioning 'human-readable' twice, but the length is justified by the need to compensate for the sparse schema and absent output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must explain return values, and it does: it provides the exact dict shape and notes stdout is human-readable. It also covers parameter semantics, error behavior, and when to prefer buildx_list. Nothing needed to call this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It fully documents both parameters: name defaults to the active builder, and bootstrap boots the builder if it isn't running. No parameter is left unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Inspect a builder instance.' It then clarifies the scope by noting it returns human-readable detail for one builder and explicitly contrasts this with buildx_list, which returns JSON for all builders. This clearly distinguishes 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names buildx_list as the alternative for machine-parsed JSON covering all builders, and states that buildx_inspect is for human-readable detail on one builder. It also advises calling buildx_list when JSON output is needed, giving the agent clear routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond that: it states that the tool raises RemoteFailureError on CLI failure, specifies the return format ("One dict per builder (parsed from `--format '{{json .}}'`)"), and discloses truncation handling (dropping last partial record if MAX_CLI_OUTPUT_BYTES is exceeded). These are non-obvious traits that materially affect invocation and result interpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: the primary action appears in the first sentence, followed by differentiation, error behavior, and return details. Each sentence carries distinct information without redundancy. The use of a Returns section is clean and keeps the main body concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only list tool, the description is fully complete. It explains the output shape, the error condition, and how truncation is handled. It also points to relevant siblings. There is no missing information an agent would need to invoke or interpret the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema is an empty object (0 parameters), so there is nothing for the description to explain. Per the rubric, the baseline for 0 parameters is 4. The description does not add or need to add parameter semantics since none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise statement — "List builder instances" — which is a specific verb+resource pair. It further differentiates from siblings by calling it a "Machine-parsed view of every builder" and explicitly naming `buildx_inspect` (for one builder's human-readable detail) and `buildx_use` (to switch the default). This makes the tool's role unmistakable relative to its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly directs when to use alternatives: "use `buildx_inspect` for one builder's human-readable detail and `buildx_use` to switch the default." This provides clear context on when this tool is appropriate and when a sibling is preferable, leaving no ambiguity for the agent.

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

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

The description goes well beyond the annotations by revealing that the tool always passes --force, does not raise on non-zero CLI exit (except for missing plugin or timeout), and returns a structured result dict. It also states destructive behavior directly, reinforcing the destructiveHint annotation 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized: critical safety warning first, then execution-behavior caveat, then a compact parameter list with examples, then the return shape. No redundant sentences or filler; every section earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, complex CLI wrapper with no output schema, the description is complete: it covers all parameters, return values, error behavior, timeout defaults, and a safety recommendation to pair with buildx_du. Nothing needed for correct invocation is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates fully by explaining every parameter: all, filters with an example, reserved_space, max_used_space, min_free_space, builder, and timeout_seconds. This adds real 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Remove BuildKit cache entries.' It also clearly distinguishes this from related tools like buildx_du by positioning this as the destructive counterpart and by naming the cache-specific scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises pairing with buildx_du first to inventory what would be removed, which is strong practical usage guidance. It also warns about the tool's exit-code behavior Rhino so the agent knows to inspect returncode/stderr, but it does not formalize when to choose this tool over image_prune or volume_prune.

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

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

The description goes beyond annotations (readOnlyHint=false, destructiveHint=true) by detailing what is destroyed (build cache), how to preserve it (keep_state=True), and the error-handling behavior (does not raise on non-zero CLI exit but does on missing plugin/timeout). This adds significant 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the primary action, but includes slight redundancy (e.g., 'Remove a builder instance' and 'Deletes a builder made by buildx_create'). Nevertheless, every sentence provides necessary detail, and the arg descriptions are efficiently formatted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all parameters, return format (dict with returncode, stdout, stderr, truncated), error behavior, and relationship to siblings. It is sufficient 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description fully compensates by explaining each parameter in the 'Args' section: name (mutually exclusive with all_inactive), all_inactive, keep_state, keep_daemon, and force. 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Remove a builder instance' and specifies it deletes builders made by buildx_create, distinguishing it from buildx_prune (which reclaims cache while keeping the builder). This is a specific verb+resource with explicit differentiation 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly advises using buildx_prune when wanting to reclaim cache while keeping the builder, providing a clear alternative and condition for selection. It also notes the tool is for builders created by buildx_create, giving context on 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.

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

The description adds meaningful behavioral context beyond the annotations: it discloses that a non-zero CLI exit does not raise, exceptions for missing plugin/timeout still raise, and the agent must inspect returncode/stderr. It also explains the persistence/storage implications of default vs. global_default, which is not inferable 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than minimum but every section earns its place: opening one-line purpose, scoping semantics, sibling routing, error behavior, and Args/Returns guides. The prose's key points are front-loaded. Minor redundancy exists because the Args section restates persistence semantics already given in the prose, but it serves as a practical quick-reference.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition covers the tool's output format, exception behavior, parameter semantics, and relation to siblings, and it explicitly documents the returned dict since there is no output schema. It gives an agent everything required to select and invoke the tool correctly, including which default flags to use and how to handle the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, yet the description's Args section gives each parameter a concrete meaning: name is the builder from buildx_list, default persists for the current Docker context, and global_default persists across all contexts. This fully compensates for the sparse schema and tells the agent the exact behavioral consequences of each flag.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Select the active builder for subsequent buildx operations') and clearly distinguishes itself from siblings by recommending buildx_list for discovery and buildx_build as a direct builder-passing alternative. This resolves ambiguity without needing to inspect other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly directs the agent to use buildx_list to see available builders and to pass a builder name via buildx_build when a global default switch should be avoided. The scoping rules for session, Docker context, and all contexts are explicitly stated, giving precise when-and-when-not conditions.

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

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

Beyond the sparse annotations, the description discloses important runtime behavior: it does not raise on a non-zero CLI exit, but a missing compose plugin or timeout still raises; callers should inspect `returncode`/`stderr`. It also notes that `project_dir` may be copied to the target host when no local plugin exists, which is useful contextual behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured: a one-line summary, a differentiation note, a behavior warning, an Args list, and a Returns block. Every sentence adds operational value, and the content is front-loaded with the most important scoping detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, seven optional parameters, and sparse annotations, the description compensates fully: it documents all parameters, specifies the exact return dictionary, and explains failure semantics. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. It does so thoroughly: all seven schema properties are documented with meaning, defaults, and Docker-flag equivalences (e.g., `files` as repeatable `-f`, `services` defaulting to all, `timeout_seconds` defaulting to 1800).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Build images for a compose project.' It further narrows scope to the project's `build:` sections and explicitly contrasts with `compose_up(build=True)`, which also builds. This clearly differentiates the tool from siblings like compose_up and buildx_build.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to guidance: use this tool to build images without starting anything, while `compose_up(build=True)` is named as the alternative for build-and-start in one step. This leaves little ambiguity about how to select between the two closely related compose operations.

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

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

Beyond the annotations (readOnlyHint, destructiveHint), the description adds critical behavior: it does not raise on non-zero CLI exit, but does raise on missing plugin or timeout, and warns that config may be None on failure with a pointer to inspect raw.stderr. It also explains the return format when format='json'. These details disclose exactly how the tool behaves in edge cases, enriching 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: it front-loads the core action, then usage, then error/return behavior, then parameters. Each sentence adds value without redundancy. The argument list is compact yet informative, and the return format is explicitly defined. No filler or repetition exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all essential aspects for correct invocation: purpose, usage context, error handling, parameter semantics, and return structure (including the dict format and how config changes with format). It even notes the target-host copy nuance. Given there is no output schema, this is fully complete for a read-only config tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description fully carries the burden. All 6 parameters are individually described with meaning, defaults, and even CLI flag equivalences (e.g., 'repeatable, `-f`' for files, '`--services`' for services_only). It also notes 'project_dir' is copied to the target host when no local plugin. This adds significant semantic value beyond the raw schema, which only has types and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and object: 'Render the canonical compose configuration after merges, profiles, and variable substitution.' It then states its intended use: 'validate compose files and see exactly what the CLI will run before compose_up.' This clearly differentiates it from sibling compose tools like compose_up (which executes) and compose_ps (which lists services), 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly suggests using this tool to validate and preview the configuration before running compose_up, giving a strong context and timing for use. It does not list alternative tools or state when not to use it, but the phrase 'before compose_up' implicitly positions it as the inspection counterpart to the execution tool, which is sufficient for guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses non-obvious behavioral traits: it does not raise on a non-zero CLI exit but does raise on missing plugin/timeout, it refuses container->host copies when the local destination already exists, and it has a CapabilityError case for unix:///tcp://+TLS hosts. These details go far beyond what the annotations supply and fully characterize the tool's fault model.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but each paragraph carries a distinct load: overview, stdout limitation, error semantics, SSH fallback, unix:///tcp:///cases, parameters, and return form. There is minor redundancy (the 'no local compose plugin' condition appears twice) and the density risks truncation in the UX, but the structure is logical and mostly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 8 parameters, no output schema, and no schema-described fields, the description is complete: it writes the return shape (returncode/stdout/stderr/truncated), the error taxonomy (non-zero exit, missing plugin, timeout, CapabilityError), the host-permission exposure, and the remote-host fallback semantics. An agent has everything needed to call it correctly without needing supplementary documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero parameter descriptions (0% coverage), so the description completely compensates. Each of the eight parameters gets meaningful detail: source/dest format, index for replicas, all_containers semantics, project_dir default and remote-copy behavior, repeatable files, project_name override, and timeout_seconds default. This fully equips the agent to pass correct args without opening the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: "Copy files/folders between a service container and the server host's filesystem." It also explains the required source/dest format (SERVICE:PATH on exactly one side) and explicitly excludes copying to stdout, which distinguishes it from related tools like container_archive_get and container_archive_put.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description names when to use alternative tools: copying to stdout should use container_archive_get; unix:///tcp://+TLS hosts without a local plugin should use container_archive_put or container_archive_get_to_file. It also explains the SSH fallback behavior and when the tool is not covered, giving the agent clear decision rules for choosing this tool vs. alternatives.

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

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

Beyond the destructiveHint annotation, the description discloses meaningful behaviors: images are kept, named volumes are only removed with volumes=True, non-zero CLI exits do not raise, and missing plugin/timeout conditions still raise. It also tells the agent to inspect returncode/stderr, which is valuable runtime context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized and front-loaded: a one-sentence purpose, a short behavioral note, then structured Args and Returns sections. Every sentence adds information without unnecessary padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive compose operation with no output schema, the description provides the return dict shape, subprocess error semantics, and parameter meanings. The only notable gap is the undocumented 'profiles' parameter, which prevents it from being fully complete for all 7 inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It explains six of seven parameters with useful detail (project_dir default/copy behavior, repeatable -f files, volumes destructive flag, timeout default). However, the 'profiles' parameter in the schema is not mentioned at all, leaving one parameter undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action and resource: 'Stop and remove containers, networks (and optionally volumes) for a compose project.' It also explicitly names itself as the inverse of compose_up, which clearly differentiates it from compose_stop and other compose-related siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly contrasts with compose_stop ('Use compose_stop to stop without removing anything') and states when the destructive volume removal applies (volumes=True). This gives an agent clear routing guidance among related compose lifecycle tools.

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

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

Goes beyond the generic readOnlyHint/destructiveHint annotations by disclosing that -T is always passed, that non-zero CLI exits do not raise exceptions, that exec-form argv avoids shell interpolation, and which failure modes still raise. These are material behavioral details an agent needs to 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-factored: opening purpose, then critical execution notes, then an Args list, then Returns. Each sentence earns its place—no fluff, no repetition of schema types. The front-matter covers the most important operational caveats before the parameter list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters foreseeable, no schema descriptions, no output schema, and nested object inputs, this description provides all essential context: command form, error behavior, parameter meanings, default values, and return structure. There is no missing information required to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description must fully compensate. It provides concise, meaningful descriptions for all 10 parameters, including defaults, semantics like 'repeatable, -f', and context such as 'container index when service has multiple replicas'. This gives the agent everything needed to populate each parameter correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Run a command inside an already-running compose service container'. The qualifier 'already-running' distinguishes it from compose_run and container_run, and it explicitly points to the sibling container_exec. This is a precise, unambiguous purpose statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context by specifying the target is an already-running compose service, which implies not for stopping containers or non-compose containers. Mentions 'see also container_exec' but does not explicitly state when to choose one over the other. This is clear context without formal exclusions.

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

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

Annotations already mark it read-only and non-destructive, and the description adds meaningful behavior beyond that: it parses --format json, requires containers to exist, raises RemoteFailureError on CLI failure, and explains project_dir copying behavior on remote hosts. This gives the agent a clear behavioral contract.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, then uses a compact Args/Returns layout. Every sentence contributes: purpose, usage context, error behavior, parameter semantics, and return shape. There is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description covers all essentials: what the tool does, when to use it, prerequisites, failure mode, parameter meanings, and the exact return structure. An agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It does so for all four parameters: project_dir default and remote-copy behavior, files as repeatable -f paths, project_name as override, and services as a restriction with default all. This fully compensates for the empty schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List the images used by a compose project's services.' It also clarifies the exact question the tool answers and explicitly distinguishes itself from compose_ps and image_list, making sibling differentiation immediate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when the tool is appropriate, requires containers to exist and compose_up to have been run first, and names alternatives for adjacent concerns: compose_ps for container state and image_list for daemon-wide images. This is explicit when/when-not guidance.

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

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

While annotations already mark destructiveHint=true, the description adds substantial behavioral context: the immediate kill with no grace period, the non-raising behavior on non-zero CLI exits, the specific exceptions that still raise (missing plugin, timeout), and the project_dir copy-to-host behavior. These traits are not captured by the annotations and are crucial for an agent to predict 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: purpose in the first line, behavioral caveats in a short second paragraph, then a compact Args list and a Returns line. Every sentence adds information; there is no filler. The front-loading of purpose and the most important caveat ('prefer compose_stop') makes it easy for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema, the description is complete. It explains all parameters, return values (dict with returncode/stdout/stderr/truncated), the destructive nature, and the nuanced CLI-exit behavior. Combined with the annotations, an agent has everything necessary to invoke the tool correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description fully compensates by documenting all 6 parameters in the Args section. Each parameter gets an explanation beyond the schema's type/default: 'services: Restrict to these services (default: all)', 'signal: Signal to send (default "SIGKILL"; e.g. "SIGTERM", "SIGHUP")', and 'files: Explicit compose file paths (repeatable, `-f`)'. This adds real semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb phrase: 'Send a signal to a compose project's containers (default SIGKILL).' It explicitly identifies the resource (compose project containers) and the action (send signal), and it differentiates from the sibling compose_stop by noting the default signal and the 'prefer compose_stop' guidance. This leaves 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('Immediate, with no grace period') and when to prefer an alternative ('prefer `compose_stop` for a clean shutdown (stop signal, then kill after a timeout)'). It also provides a behavioral guideline for error handling: 'Does not raise on a non-zero CLI exit ... inspect `returncode`/`stderr` in the result.' This is explicit when/when-not guidance with a named sibling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds that it raises RemoteFailureError on CLI failure, which is useful for error handling, and indicates the output format (parsed from --format json). However, it doesn't detail what happens if the daemon has no projects or how errors beyond RemoteFailure are handled—for a read-only list tool, this 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief with no fluff: three sentences cover purpose, differentiation, error behavior, and parameter note. Key info is front-loaded with a clear structure (function, comparison, error, parameter). It earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a simple list tool: it states what it returns (dict per project), how it behaves (raises error), and how it differs from compose_ps. The single parameter 'all' is explained. No output schema exists, but the Returns section covers it. Minor gap: could mention sorting or ordering, but not essential; scores high but not perfect for a straightforward list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds a brief note for the 'all' parameter: 'Include stopped projects', which directly clarifies its meaning beyond the schema's type/boolean/default. This adds some value, but not extensive detail like default behavior or implications of not setting it. Given the parameter is simple and boolean, this is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists compose projects known to the daemon across all directories, with a specific 'project-level view' scope. It also distinguishes itself from compose_ps, which lists containers of a single project, clarifying its unique function among sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly contrasts with compose_ps: use compose_list for project-level visibility, and compose_ps when you need container details of one project. This provides direct guidance on when to use this tool vs. the alternative, leaving no ambiguity.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses non-following behavior, promptness, that log text goes to stdout, that a non-zero CLI exit does not raise but must be inspected via returncode/stderr, and that missing plugin or timeout still raises. It also notes project_dir is copied to target host if no local plugin. This is rich behavioral context well beyond 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a brief front-loaded behavioral statement, a clearly separated Args list, and a Returns section. Every sentence adds value—no filler. The Arg explanations are concise but complete, with inline examples where needed. The format is scannable and appropriately sized for an 8-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description provides the return format (dict with returncode/stdout/stderr/truncated). It covers error behavior (non-zero CLI exit, missing plugin, timeout), parameter semantics, and usage alternatives. There is no obvious missing information an agent would need to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden. It explains every parameter in the Args section: default behavior for project_dir, repeatable -f for files, override for project_name, restriction semantics for services, tail with 'all' and MAX_CLI_OUTPUT_BYTES cap, since/until with examples, and timestamps flag. This compensates fully for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise action and resource: 'Fetch a bounded slice of logs from a compose project' and immediately disambiguates from siblings by naming container_logs and service_logs as alternatives. It also states a key scoping trait (never follows), making the tool's purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent when to use this tool versus siblings: 'For one container's logs use container_logs; for a swarm service use service_logs.' It also clarifies behavior that affects when it is appropriate (bounded, non-following, 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.

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

With only readOnlyHint and destructiveHint annotations (both false), the description carries the burden of behavioral details and does so well. It explains the meaning of pause (CPU stops, memory/network/state retained), and precisely discloses error-handling behavior: non-zero CLI exits do not raise, but a missing plugin or timeout does.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Each section is purposeful: a crisp purpose sentence, a short contrast-and-consequences paragraph, a compact Args list, and a Returns line. The structure is front-loaded with the most important decision (pause vs stop vs down) and the content respects the agent's time.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's behavior, alternatives, error handling, all parameters, and the return dict shape. There is no output schema, so the explicit `Returns: dict...` line is genuinely necessary and sufficient. For a tool of this complexity, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. The Args section provides meaningful context for every parameter: `services` restricts targets, `project_dir` identifies the compose file location and even notes the copy-to-host nuance, `files` supports repeatable `-f` usage, and `project_name` overrides the project name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource combination ('Pause the containers of a compose project') and immediately clarifies the semantics with 'freezes their processes in place.' It also names the relevant siblings (`compose_unpause`, `compose_stop`, `compose_down`), making it easy to distinguish from nearby tools like `container_pause`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains exactly when to use this tool: when you want to freeze containers without releasing resources. It explicitly contrasts it with `compose_stop` (stop and free resources) and `compose_down` (stop and delete), and points to `compose_unpause` for resuming, giving clear if-then guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context beyond that: `published` is None when unpublished, `bindings` can contain multiple entries for addresses like IPv4/IPv6, and RemoteFailureError is raised on CLI failure. It also discloses copy-to-host behavior for project_dir, which is not visible in the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then adds a one-line analogy, targeted edge cases, and compact Args/Returns sections. No sentence is wasted, and the structure makes it easy to scan before invoking the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description supplies a detailed return contract including the returned keys and the distinction between the first binding and the full bindings list. It also mentions the failure exception and parameter defaults, making the tool fully actionable without external lookups.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate fully, and it does. Every parameter has an explanatory line: service, private_port, protocol with default, index, project_dir with default behavior, files with `-f` repeatability, and project_name. This materially helps an agent select and fill parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Resolve the host binding for a service's container port.' It names the Docker equivalent (`docker port`) and states the exact question answered. It also distinguishes itself from `container_inspect` by directing non-compose containers elsewhere, making its scope unambiguous among the large sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit alternative and the condition under which to use it: 'For non-compose containers read container_inspect's NetworkSettings.Ports instead.' It also describes the compose-specific context and the fallback/default behavior for project_dir. This gives an agent clear routing instructions without needing to inspect sibling tools.

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

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

Annotations already supply readOnlyHint and destructiveHint, but the description adds valuable context: it does not raise on non-zero CLI exits (with exceptions for missing plugin/timeout), and it explains the fallback of inspecting `raw.stderr`. It also notes that `project_dir` is copied to the target host if no local plugin. These behaviors go beyond the annotations and are crucial for correct invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized and front-loaded with purpose, followed by alternatives, behavior, and parameters. It is somewhat lengthy but every sentence earns its place. The parameter list and return format are explicitly labeled, making it easy to parse. Slight verbosity in the return section could be trimmed, but overall it is compact for the amount of information conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no output schema, and no param descriptions in the schema, the description fully compensates: it defines each parameter, states the return dict shape, and covers error handling. It also positions the tool among siblings. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does, by explaining each parameter: `project_dir` (default and copy behavior), `files` (repeatable), `project_name` (override), `services` (filter), and `all` (include stopped). This gives agents enough meaning to set each argument correctly without needing a schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'List containers in a compose project, parsed from `--format json`.' It immediately distinguishes itself from siblings by stating that `compose_list` enumerates projects and `container_list` covers non-compose containers, so an agent can pick the right tool without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool (container-level view of one project) and names the alternatives (`compose_list` for projects, `container_list` for non-compose). It also gives a behavioral note about non-zero exits guiding the agent to inspect `raw.stderr`. This is explicit usage guidance with no ambiguity.

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

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

Beyond the sparse annotations, the description clearly discloses non-raising behavior on non-zero CLI exits, the specific exceptions that still raise (missing compose plugin or timeout), and instructs the agent to inspect `returncode`/`stderr`. It also documents the return dict structure and notes that images are fetched without starting containers, giving a clear behavioral model.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then moves to use cases, exclusions, behavioral caveats, parameter explanations, and return format. Every sentence adds operational value, and the structure makes it easy for an agent to quickly extract invocation requirements without scanning filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description explicitly provides the return dict shape. It covers auth prerequisites, error semantics, parameter defaults, and the relationship to compose_up. For a tool with six parameters and meaningful failure modes, this description is complete enough for an agent to call it correctly and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the input schema has 0% property descriptions, the description's Args section fully compensates by explaining all six parameters: project_dir, files, project_name, services, ignore_pull_failures, and timeout_seconds, including defaults, repeatability, behavior when omitted, and the target-host copy nuance. This is exactly what the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Pre-fetch images for a compose project's services without starting them." It immediately distinguishes itself from compose_up by clarifying the pull-only scope, and reinforces the purpose with concrete intents like staging images and verifying accessibility without starting containers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use scenarios (before outage windows, refreshing cache, verifying access) and names the key alternative: `compose_up --pull always`, explaining that compose_pull should be used when the pull step needs to be separated. It also provides the auth prerequisite with `system_login`, leaving little ambiguity about 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.

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

Beyond annotations (which are minimal: destructiveHint false, readOnlyHint false), the description discloses crucial behavior: it does not recreate containers, it passes through non-zero CLI exits without raising (unless missing plugin/timeout), and it copies project_dir to the target host if no local plugin. These are essential for correct invocation and result interpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then provides usage guidance, behavioral notes, and a structured Args/Returns section. Each sentence earns its place; no filler or redundancy. The layout makes it easy to scan and parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema, the description covers all necessary operational context: when to use, how to interpret results, exit-code behavior, and parameter defaults. An agent has everything needed to invoke it correctly, including the return dict structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates by explaining all six parameters with clear semantics: project_dir default and copy behavior, files repeatable -f, project_name override, services subset, stop_timeout_seconds grace period, and timeout_seconds subprocess timeout. Every parameter is meaningfully described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb and resource: 'Stop then start services without recreating containers or applying config changes.' This clearly distinguishes it from compose_up and other compose commands, and the phrase 'bounce a service' adds concrete intent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use this tool ('to pick up a runtime file change or clear an in-memory state') and when not to, directing to `compose_up` if the compose file has changed. Also explains the stop_timeout_seconds behavior and the non-zero exit handling.

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

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

The description discloses behavior not visible in annotations: it forces -T, defaults to detached with --rm, creates a new container, and does not raise on non-zero exits (only plugin/timeout failures raise). This gives an agent accurate expectations for result handling and 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured: two behavior paragraphs, a compact Args list, and a Returns line. There is no redundant content or filler, and the most important runtime caveats are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 13 parameters, no output schema, and several runtime caveats, the description covers invocation, defaults, error behavior, and return structure. The only minor omission is explaining the `truncated` flag semantics, but this is not needed to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the Args block compensates by explaining every parameter, including non-obvious semantics: command is exec-form without a shell, project_dir is copied to target host if no local plugin, and timeout_seconds defaults to 600. This materially exceeds the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with 'Run a one-off command against a compose service,' naming a specific verb, resource, and scope. It then distinguishes itself from compose_exec ('starts a NEW container rather than running inside the existing one'), making the tool unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear differentiation from compose_exec, one of the most likely alternatives, and gives concrete runtime conditions ('Always passes -T', 'Defaults to detached with --rm'). It doesn't enumerate every alternative compose subcommand, but the one-off framing plus the explicit contrast is sufficient guidance.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false, which are minimal. The description adds valuable behavioral context: it does not raise on non-zero CLI exit, but does raise on missing plugin or timeout, and instructs the agent to inspect returncode/stderr. It also notes that project_dir is copied to the target host if no local plugin. This goes beyond the annotations 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: a clear first sentence, a short paragraph distinguishing it from siblings, a note about error behavior, and a bulleted Args list. Every sentence earns its place, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 optional parameters, no output schema, and minimal annotations, the description covers the key aspects: what it does, when to use it, how it behaves on errors, and what each parameter means. It also documents the return dict shape. The only minor gap is that it doesn't describe what 'truncated' means in the return value, but that is a small omission given the overall completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It provides a one-line explanation for each of the five parameters, including defaults (project_dir defaults to server cwd, timeout_seconds defaults to 600s). This is sufficient for an agent to understand what each parameter does, though it doesn't go into deep detail about formats or edge cases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Start existing (stopped) containers of a compose project.' It explicitly distinguishes itself from compose_stop and compose_up, making it clear what this tool does and does not do. The first sentence is precise and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names the counterpart (compose_stop) and the alternative (compose_up), and states the condition for choosing each: 'starts existing containers without recreating them' vs 'use compose_up to (re)create containers from the compose file.' This is exactly the kind of when-to-use guidance an agent needs.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond these: it clarifies that state persists (containers/networks/volumes survive), explains that non-zero CLI exits do NOT raise except for missing plugin/timeouts, and warns that project_dir may be copied to the target host. This contextual detail is valuable and consistent with 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly written and well-organized. It starts with a one-sentence purpose, immediately contrasts with siblings, then lists parameters and return value. Every element contributes essential information with no fluff or redundant phrasing. The structure front-loads the most critical decision points (what survives, error handling) before details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (six parameters, non-standard exit handling), the description covers everything needed for correct invocation: purpose, persistence semantics, error behavior, parameter meanings, and the exact return dictionary format. The sibling set is large, but the description clearly distinguishes this tool from the most similar alternatives (compose_down, compose_start). No missing information is apparent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides a full list of all six parameters with clear, human-readable explanations and defaults where applicable (e.g., 'default: server cwd', 'default: all', 'default 300s'). The schema itself has zero property descriptions (0% coverage), so the description completely compensates, leaving no parameter underdocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Stop services in a compose project without removing their containers' – a specific verb, resource, and clear scope. It immediately differentiates from the sibling compose_down by stating what is NOT removed, and explicitly names compose_start as the reverse operation. This leaves no ambiguity about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool versus alternatives: 'Unlike compose_down, containers/networks/volumes survive - use compose_start to bring them back.' It also explains the non-zero exit behavior and the copying of project_dir when no local plugin exists, giving the agent concrete conditions for invocation.

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

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

The annotations mark this as read-only and non-destructive, and the description adds substantial behavioral detail: output is ps-style text on stdout rather than JSON, non-zero CLI exits do not raise while missing plugin or timeout do, and returncode/stderr should be inspected. This goes well beyond the annotation hints and gives an agent realistic expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a short purpose sentence, a behavioral/error note, and compact Args/Returns sections. Every sentence earns its place: output format, error behavior, parameter meanings, and result shape are all necessary and presented without filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the Returns dict shape is explicitly provided. All optional parameters are explained, output format is identified as non-JSON stdout, and unusual error behavior is disclosed. Nothing essential for invoking compose_top correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the burden for parameters. It defines all four: services restricts scope, project_dir supplies default and a copy-to-host behavior, files are repeatable and map to -f, and project_name is an override. Each parameter gets meaningful semantics beyond the bare schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Show the running processes of a compose project's containers.' It further distinguishes itself by noting the per-container equivalent is container_top and clarifies the output is a ps-style process table per service, not JSON. This clearly separates it from siblings like compose_ps and container_top.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states clear context: use for compose project containers, with container_top named as the per-container equivalent. It does not enumerate when-not-to-use scenarios or compare against compose_ps, but the project-versus-container distinction gives enough guidance for an agent to select this tool correctly.

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

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

The annotations only indicate that this is not read-only and not destructive; the description adds meaningful behavioral detail: processes continue from where they were frozen without restart, a non-zero CLI exit does not raise an exception, and project_dir may be copied to the target host when no local plugin exists. This goes beyond the annotations and helps the agent predict side effects and error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: the core action appears first, followed by sibling distinctions, error behavior, parameter definitions, and return type. Every sentence carries useful information and no filler or redundant restatement is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no required parameters, no output schema, and moderate complexity, the description is complete: it documents all parameters with defaults and behavior, explains return values, distinguishes related tools, and discloses error-handling quirks. There is no missing information an agent would need to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates fully by explaining all four parameters: services restricts to given services (default all), project_dir defaults to server cwd and may be copied to the target host, files accepts repeatable compose file paths via -f, and project_name overrides the project name. This adds meaning the raw schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific, unambiguous statement: 'Unpause the containers of a compose project (resumes paused processes).' It also distinguishes the tool from closely related siblings by calling itself the reverse of compose_pause and naming compose_start as the counterpart for stopped containers. An agent can immediately tell what the tool does and how it differs from similar operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly situates this tool relative to alternatives: use it to resume paused containers ('Reverse of compose_pause'), and use compose_start instead when containers are stopped. It also clarifies what does and does not raise an error, telling the agent how to interpret non-zero exits by inspecting returncode/stderr. This gives clear, actionable selection guidance.

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

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

The description discloses important non-obvious behaviors: it always runs detached, does not raise on a non-zero CLI exit, raises only on missing plugin/timeout, and copies project_dir to the target host when no local plugin exists. These details go well beyond the sparse readOnly/destructive annotations and materially affect how an agent interprets results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly organized: a one-line purpose, then behavioral caveats, a compact args list, and a return type. Each sentence earns its place, and the most important constraints are front-loaded. No fluff or repetition exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers invocation defaults, error semantics, return shape, and path handling, which is strong for a tool with no output schema. The only notable omission is the profiles parameter, so an agent would not know that profiles can be explicitly selected.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries the parameter documentation burden and documents nine of the ten parameters with useful default and behavior notes, such as timeout_seconds default 600, wait adding --wait, and pull behavior. However, the profiles parameter present in the input schema is not mentioned at all, which is a real gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb-resource pair: 'Bring up a Docker Compose project, detached.' It immediately distinguishes this from compose_stop, compose_ps, and other compose operations with an unambiguous command intent. Even without the title, the tool's purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit guidance to use compose_ps to confirm services are running, or wait=True to block until healthy. This provides clear situational usage for the common follow-up decision. It does not explicitly compare against compose_start/compose_restart, but the detached-operation context is sufficient for an agent to know when this is appropriate.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already covered. The description adds valuable behavioral context beyond that: the blocking-until-timeout behavior, the subprocess kill on timeout, the fact that exit codes are on stdout, and the nuanced exception behavior (does not raise on non-zero CLI exit but raises on missing plugin or timeout). This is rich, non-obvious behavior that an agent needs to know. It doesn't describe the full return dict, but the Returns section covers the key fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized: a one-sentence core behavior, a use-case paragraph with warnings and sibling routing, an exception note, and a compact Args list. Every sentence earns its place. The most important behavioral facts (blocking, timeout, exit codes) are front-loaded before the parameter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a blocking wait tool with 5 parameters and no output schema, the description is complete. It covers the blocking semantics, timeout behavior, exit-code location, exception behavior, parameter meanings, and return dict shape. The sibling routing (container_wait, service_wait) closes the last ambiguity. There is no output schema, so the Returns section is necessary and present. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all five parameters. It does: services (one or more, at least one required), project_dir (default server cwd, copied to target host if no local plugin), files (explicit compose file paths, repeatable -f), project_name (override), timeout_seconds (default 300s). The project_dir note about copying to the target host is genuinely useful context beyond the schema. The only minor gap is that files doesn't mention the default behavior when omitted, but the schema's default:null plus the project_dir note covers the common case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Block until the named service containers stop, then return their exit codes.' It clearly distinguishes this from sibling tools by naming container_wait and service_wait as alternatives for different scopes. The one-shot/batch use case is stated explicitly, so an agent can tell this apart from compose_stop, compose_run, or container_wait without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'For one-shot / batch services' and warns that long-running services block until timeout. It names alternatives directly: 'For a single container use container_wait; for swarm services use service_wait.' It also states when it does not raise (non-zero CLI exit) versus when it does (missing plugin or timeout), which is essential for correct invocation.

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

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

Beyond the annotations, the description discloses that configs are immutable, not encrypted at rest, require a swarm manager, and that data must be raw bytes with encoding guidance for strings. This gives an agent clear expectations about the tool's behavior and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured, front-loading the core purpose before param details and return information. Every sentence adds value, with an example for templating and clear guidance for data encoding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description explicitly documents the return value shape. It also covers usage constraints, alternatives, immutability implications, and all four parameters, leaving little an agent would need to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description explains every parameter meaningfully: name uniqueness, raw byte content, label assignment, and templating driver config with a concrete example. It compensates fully 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it creates an immutable Swarm config object with a specific verb and resource. It distinguishes itself from secret_create by noting configs are not encrypted at rest, and hints at its role of mounting files into service containers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance: use secret_create for credentials or keys, and explains the update workflow by creating a new config and removing the old one with config_remove. It also states the prerequisite that a swarm manager is required.

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

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

Annotations already mark this as read-only, and the description adds valuable behavioral context: config payloads remain readable and are base64-encoded in Spec.Data. This goes beyond the annotations and warns the agent about an unusual security-relevant behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description front-loads the core action in the first sentence, then adds only high-value context: the prerequisite, the comparison to secrets, the input form, and the return shape. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description adequately describes the return document fields. The single parameter's semantics are explained, the required environment is stated, and the alternative listing tool is named. Nothing needed for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only provides a bare string parameter, but the description clarifies that id_or_name accepts either a config ID or name. It also tells the agent how to discover valid values via config_list, fully compensating for the 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Get a swarm config's full inspect payload by id or name.' It clearly differentiates itself from config_list (enumerate vs read one) and 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: after enumerating with config_list, and when the full payload is needed. It also notes the requirement for a swarm manager and contrasts configs with secrets, helping the agent choose correctly among similar inspect tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: configs are not treated as sensitive so Spec.Data is included base64-encoded, and the output is a list of full config documents. This covers the meaningful behavior for a read-only list operation, though it omits error/pagination details that are less critical here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-structured: a one-line core statement, a differentiating note, a filter-keys sentence, then clean Args/Returns sections. Every sentence adds value, and the most critical information (what it lists, prerequisite, and alternative) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with one optional parameter and no output schema, the description covers scope, prerequisite, filtering options, return format, and the sibling for single-config access. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema's only parameter (filters) has zero description coverage, so the description carries the burden. It compensates by explaining the parameter's purpose ('Narrow the list; omit to return every config') and enumerating valid filter keys (id, name, names, label with key or key=value), which is meaningfully more than the schema's bare object type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('List swarm configs') and states the prerequisite ('requires a swarm manager'). It distinguishes this tool from secret_list (configs include actual data, not treated as sensitive) and from config_inspect (single config by id/name), making sibling differentiation clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: the swarm manager prerequisite, valid filter keys, the option to omit filters to return everything, and the alternative tool for fetching a single config by id/name (config_inspect). An agent can decide correctly without opening the schema.

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

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

Annotations already mark destructiveHint=true, but the description adds valuable behavioral context: the failure mode when services reference the config, the manager requirement, and the return value (bool: True after removal). This goes beyond what annotations provide, disclosing operational constraints 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core action. The 'Returns:' line is slightly redundant given the output schema exists, but it is not excessive. The structure is clear with prerequisites and context presented early, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only one parameter and an output schema, the description covers the essential operational details: prerequisites (swarm manager), failure condition (services referencing config), and its role in the rotation flow. It is sufficient for an agent to invoke it correctly. The reference to config_create provides workflow context. Minor gaps like the exact format of id_or_name are not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. However, it does not explain the 'id_or_name' parameter beyond the obvious name. It does not specify that it is the config's identifier or how it should be formatted. The parameter name is self-explanatory, but the description adds no additional semantic clarity, leaving the agent to infer from the parameter name alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Remove') and the resource ('a swarm config'), distinguishing it from related config tools like config_create and config_list. It even references the rotation flow, linking it to config_create. This is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage conditions: requires a swarm manager, and fails if any service still references the config, advising to update/remove those services first. It also places the tool as the last step of a rotation flow described in config_create. This gives clear context for when to use it, though it doesn't explicitly mention alternatives or when not to use it.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: the in-band size cap, the MCP base64 encoding rationale, the ToolInputError abort condition, and the return shape. It doesn't fully describe the contents of the `stat` dict, which is a minor transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The structure is scannable: purpose first, then explanation of why in-band is limited, then Args and Returns. The default 32 MiB is stated twice (once in the prose and once in the Args block), but the overall length is still reasonable and the extra explanation earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description appropriately documents the return keys (`archive` and `stat`) and explains the error cap behavior and the size constraint. The main completeness gap is again the undocumented required `id_or_name` parameter, so it falls just short of fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The Args block gives useful semantics for `path` and `max_bytes`, including the default and error behavior. However, schema_description_coverage is 0% and the required `id_or_name` parameter is missing from the Args section entirely, leaving the parameter documentation incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence uses a specific verb and resource ('Retrieve a file or directory from a container as a tar archive') and clearly communicates the in-band return mode. It also differentiates this tool from its sibling `container_archive_get_to_file` by explicitly noting the streaming alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives practical guidance on choosing between this tool and `container_archive_get_to_file`: it explains that in-band bytes are capped to a default of 32 MiB and that the sibling streams to a host path instead. It stops short of an explicit 'use X when Y, do not use when Z' structure, so not a 5, but the usage context is clearly present.

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

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

Beyond the annotations, the description discloses key behaviors: it streams straight to disk with no in-band byte cap, the file is written by the server's user, `~` is expanded, and existing files are refused unless `overwrite=True`. These details are not available from annotations or schema and materially affect invocation and error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the core purpose and variant distinction first, followed by inline argument definitions and a return structure. Each sentence adds useful information without filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description provides the return structure, destination handling details, overwrite behavior, and comparison to relevant siblings. This is complete enough for an agent to invoke the tool correctly in most situations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description compensates for most parameters by explaining `path`, `dest_path`, and `overwrite` semantics. It omits an explanation of `id_or_name`, though the schema marks it required and its meaning is inferable from the tool name. The return shape is also usefully described, but the missing parameter note prevents a perfect score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action—retrieve a file or directory from a container as a tar archive written to a host file—with a clear destination. It also explicitly distinguishes itself from the sibling `container_archive_get` as the file-writing variant, so an agent can select it correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage guidance: prefer this over `container_archive_get` for large payloads because in-band bytes are base64-encoded, and use `container_export` for the whole filesystem. This directly addresses when to choose this tool over alternatives.

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

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

Description adds meaningful transparent behavior beyond annotations: inversion relationship, base64 encoding of in-band bytes, server-user reading of from_file, and ~ expansion. It omits overwrite semantics on extraction but disclosures are strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose, compact and organized into a lead paragraph followed by Args/Returns sections. Every sentence carries information; only a small redundancy between the prose and the Args list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for the tool's complexity: covers purpose, extraction at path, input options, and return type bool. Minor gaps such as overwrite at destination and effects of partial extraction remain but are not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description fully compensates by explaining the meaning of path, data, and from_file and their mutual exclusivity. only id_or_name lacks explanation, but it is inferable from container context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Upload a tar archive to a path inside a container'), names the inverse operation (container_archive_get), and makes the extraction semantics clear. The tool is immediately distinguishable from all siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the inverse tool and the mutually exclusive data vs from_file options, and recommends from_file for large archives due to MCP base64 encoding. The requirement that path must already exist is also stated.

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

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

Without useful annotation detail (readOnlyHint=false and destructiveHint=false are generic), the description carries the behavioral burden. It discloses a key runtime behavior: 'The container is paused by default during the snapshot to ensure filesystem consistency.' It also explains the effect of changes ('Dockerfile instructions to apply on top of the snapshot') and the return value ('full inspect payload (Id is the new image id)'). This is transparency beyond any structured field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a one-sentence summary, then supplies usage context, an alternative, behavioral notes, and a structured Args/Returns section. Every sentence adds information; there is no fluff or repetition of schema defaults except where it adds clarity (e.g., tag default). It is appropriately sized for a tool with 8 parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.