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

Beyond annotations (readOnlyHint: false, destructiveHint: false), the description discloses non-raising behavior and the subprocess nature via returncode. The cwd parameter description adds context about file copying when no local plugin. This adds significant context beyond the annotations.

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

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

The description is concise and front-loaded with the purpose, followed by a structured args list. Each sentence earns its place, and the parameter details are organized clearly without unnecessary verbosity.

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

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

The description includes the return dict format ('returncode', 'stdout', 'stderr', 'truncated'), covers all parameters, and provides usage guidance. With no output schema, this is complete for a multi-parameter build tool with potential side effects (push, load).

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

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 listing all 10 parameters with meaningful explanations, including an example for set_overrides ('app.platform=linux/amd64'), CLI flags for files ('-f'), and default values for cwd and timeout_seconds. This adds substantial meaning beyond the schema.

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

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

States the verb 'Build' with a specific resource: 'multiple targets defined in a bake file (HCL, JSON, or compose)' and differentiates from sibling buildx_build by mentioning 'for a single Dockerfile target use buildx_build'. This is a specific verb+resource+scope.

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

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

Explicitly states when to use ('Use it for multi-target builds declared in docker-bake.hcl/compose files') and provides an alternative ('for a single Dockerfile target use buildx_build'). Also notes a key behavior: 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result.'

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

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

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses substantial behavioral traits: output capture with `--progress=plain`, remote build behavior (context copying via `.dockerignore`), rejects for certain `output`/`cache_to`/`cache_from`/`ssh` combinations that would resolve on the remote machine, and the fact that stdin is not forwarded. These specifics far exceed the annotations and are crucial for safe invocation.

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

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

The description is long but every sentence adds value. It starts with a one-line purpose, then a usage paragraph, then a per-parameter breakdown with examples and restrictions. For 24 parameters, this level of detail is appropriate and well-organized into a readable list. No filler or redundant content exists.

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

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 states the return shape as `{"returncode": int, "stdout": str, "stderr": str, "truncated": bool}`. It covers remote-host fallback behavior, unsupported stdin, file path resolution rules, and timeout default. For a tool with 24 parameters and no structured output definition, this description is exceptionally complete.

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

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

Even though schema description coverage is technically 0% (no descriptions inside the schema), the tool description itself provides rich semantics for every parameter. It gives examples (e.g., `platforms` as `["linux/amd64", "linux/arm64"]`), constraints (e.g., `file` relative to server working directory, not `context`), and edge cases (e.g., `~` not expanded in `secret` `src=`). This far surpasses what the bare schema provides.

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

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

The description begins with a specific verb and resource: 'Build an image with BuildKit via `docker buildx build`.' It clearly distinguishes itself from the legacy `image_build` tool by enumerating the advanced capabilities (multi-platform, cache export, attestations, secrets, multi-stage targets), leaving no ambiguity about its scope.

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

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

Explicitly states when to use this tool: 'Replaces the legacy `image_build` tool when you need any of...' and also provides a when-not-to-use example (stdin tarball unsupported). It also documents that it always runs with `--progress=plain` and warns about remote-host restrictions, giving the agent clear decision-making context.

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

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

Despite annotations only providing readOnlyHint=false and destructiveHint=false, the description adds substantial behavioral context: non-zero CLI exits do not raise but are surfaced via returncode/stderr, config file handling and a buildx version requirement, and the side effect of `use=True` on subsequent buildx_build calls. This goes well beyond the annotations and schema.

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

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

The description is long but every sentence adds value: a one-line purpose, a crisp usage justification, behavioral caveats, and a compact parameter list. The return format is included since there is no output schema. It is appropriately dense, with no filler or repetition of annotation data.

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

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

Given the tool's complexity—9 parameters, nested objects, no output schema, and multiple behavioral caveats—the description is remarkably complete. It covers all parameters, return shape, error behavior, version constraint, and even related tool switching. An agent has nearly everything needed to invoke this correctly and understand the consequences.

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

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 all parameter meaning. It does: all 9 parameters (name, driver, driver_opts, use, bootstrap, platforms, config, node_name, append) receive brief but meaningful explanations, including transformations like driver_opts becoming `--driver-opt KEY=VALUE` and the buildx >= 0.17 requirement for config. This fully compensates for the missing schema descriptions.

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

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: 'Create a new BuildKit builder instance.' It then clarifies the purpose and distinguishes this tool from siblings like buildx_use and buildx_build by explaining when a new builder is needed (multi-platform builds, cache export). This is a textbook clear purpose statement.

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

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—'Needed when the default `docker` driver falls short'—and gives concrete use cases. It also explains the `use=True` workflow versus switching with `buildx_use`, and discusses the `bootstrap` behavior. This is strong when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context without contradicting annotations. It discloses truncation behavior, partial-record dropping, error raising (RuntimeError), and the workaround for exhaustive output. This goes well beyond the structured annotations.

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

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

The description is appropriately sized for a tool with notable caveats. It front-loads the core purpose, then provides practical warnings and finally structured arg/return notes. Every sentence adds value, and the layout is easy to scan.

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

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

Given one optional parameter, no output schema, and moderate complexity, the description covers the essential aspects: what it reports, how it might fail, how to get complete results, error behavior, parameter semantics, and return format. No significant gaps remain.

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

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

The input schema provides no description for the builder parameter, so the description's 'args: builder - Override the active builder' is essential and adds meaning. It also documents the return type as 'list - One dict per cache record'. With only one parameter, this is sufficient compensation for the 0% schema coverage.

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

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: 'Report BuildKit cache disk usage as a list of records.' It clearly differentiates from siblings by contrasting with system_df ('covers daemon-side disk, not builder cache') and buildx_prune ('Reclaim the cache').

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

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

The description provides clear usage context, explicitly noting when the tool may be insufficient (large caches exceeding MAX_CLI_OUTPUT_BYTES) and suggesting a host-side command for exhaustive reporting. It also directs to buildx_prune for reclaiming cache and clarifies that system_df is not a substitute. However, it does not explicitly enumerate alternative tools for the same job.

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

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

Annotations already indicate read-only and non-destructive behavior, but the description adds substantial behavioral detail: it parses JSON output, returns a raw fallback when output isn't a JSON object, raises RuntimeError on CLI failure, and explains how ref is normalized. This goes well beyond the annotations.

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

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

The description is well-structured with a concise purpose sentence, a return summary, and a clearly labeled args/returns section. All sentences add necessary information, and the detailed ref explanation is warranted due to the subtle behavior.

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

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

For a tool with minimal schema and no output schema, the description covers entry point, return shape, error behavior, version requirement, and parameter semantics. It is fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema has zero descriptions, but the description fully compensates with detailed param docs: ref explains the qualified vs bare id transformation, the empty/omitted case, and the ^N syntax; builder explains its default and interaction with ref. This is exemplary parameter documentation.

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

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 single build record by ref', clearly distinguishing this from buildx_history_list (listing) and other buildx tools. It further clarifies the exact scope (single record) and the debugging use case.

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

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

It explicitly frames the tool as for debugging failed or slow builds found via buildx_history_list, giving concrete context for when to use it. It also mentions the version requirement and error condition, but does not explicitly name alternative tools or state when not to use this tool.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the exact output parsing method (`--format '{{json .}}'`), the fields returned, the version requirement, and the error behavior on unsupported versions. This is valuable context that annotations do not convey.

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

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

The description is compact but information-dense: it opens with a clear purpose, then provides necessary detail on fields, usage context, version prerequisite, and parameter semantics. No extraneous content, and each sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers every important aspect: what it does, what it returns, how it behaves with older versions, and what the parameter does. It is fully self-contained for an agent to decide when to call it and how to use the results.

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

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

The input schema has one optional parameter `builder` with no description. The description compensates fully with 'builder - Builder instance to read history from (defaults to the active builder)', clearly explaining the parameter's meaning and default behavior.

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

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

The description begins with a specific verb+resource: 'List recent build records (BuildKit build history)' and clarifies that it parses the output from `--format '{{json .}}'`. It also references the sibling tool `buildx_history_inspect` for drilling into a specific build, making its role distinct.

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

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

The description explicitly states when this tool is useful: 'finding a build to drill into with buildx_history_inspect', which reveals the intended workflow and alternative. It also provides a clear prerequisite (buildx >= v0.13) and warns about the failure mode on older versions, acting as a when-to-use/check guideline.

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

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

Beyond the basic readOnlyHint/destructiveHint annotations, the description discloses critical non-obvious behavior: 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result.' It also clarifies the prerequisite that source tags must already be pushed and that append modifies an existing manifest. This adds substantial behavioral context not captured by annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by key behavioral notes, then a neatly organized args list, and finally the return type. Every sentence adds value; the text is dense but not verbose, covering all necessary details without repetition.

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

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

Given the 9-parameter complexity and absence of an output schema, the description is remarkably complete. It includes prerequisites, side-effects, failure behavior, default timeout, return format, and pointers to related tools. No important aspect is left undocumented.

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

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

The schema has no parameter descriptions (0% schema coverage), but the description's 'args' section explains every one of the 9 parameters with meaningful details, such as `target` being 'Tag for the new manifest list (-t)', `dry_run` printing without pushing, and `descriptor_files` reading from files instead of refs. This fully compensates for the schema's lack of descriptions, even providing CLI flag mappings and usage nuances.

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

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: 'Create a manifest list / OCI image index from existing per-platform tags.' It clearly distinguishes from siblings like buildx_imagetools_inspect by explicitly naming the verification tool and contrasting with docker manifest create/push.

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

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

It states when to use: 'Source tags must already be pushed; this only stitches them together' and provides an alternative: 'Replaces docker manifest create + docker manifest push.' It also recommends the next step: 'Verify the result with buildx_imagetools_inspect,' giving clear context on usage and alternatives.

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

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

Annotations already mark it read-only and non-destructive. The description adds important behavioral context: it uses the docker CLI's credential store, supports OCI indexes/attestations, and explains how `raw`/`format` change the output. It could mention whether a daemon is required, but the added value is substantial.

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

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

The description is well-structured: a one-sentence purpose, a comparative context paragraph, a concise args list, and a return contract. No redundant sentences; each part earns its place.

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

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

Given the read-only nature, 4 parameters, and no output schema, the description covers the essentials: purpose, parameter meanings, return dict, and raw/format behavior. It lacks explicit error conditions or prerequisites like buildx installation, but is still fairly complete for an inspect tool.

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

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

The schema has 0% coverage, but the description documents all four parameters: image with concrete examples, raw and format with their semantics and mutual exclusivity, and builder as an override. This fully compensates for the schema's silence.

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

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

Explicitly states the action and resource: 'Inspect a manifest in a registry without pulling.' It also distinguishes from siblings by referencing `docker manifest inspect` and `registry_manifest`, making its niche clear.

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

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

Provides direct alternatives: 'Replaces `docker manifest inspect`' and '`registry_manifest` answers the same question over direct HTTPS with no daemon or plugin.' This gives clear when-to-use guidance and context for choosing between tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result' and clarifies that stdout is human-readable. This goes beyond basic safety hints, though it could further detail error scenarios for missing builders.

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

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

The description is compact and well-structured, with clear sections for args and returns. Each sentence adds value: purpose, differentiation, exit code behavior, parameter explanations, and return format. No redundant content is present.

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

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

For a 2-parameter tool with no output schema, the description is self-sufficient. It specifies the return dict structure, parameter defaults, and non-zero exit behavior, and even points to an alternative for JSON output. This covers all essential context an agent needs.

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

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 carries the full burden. It documents both parameters: 'name' (defaults to the active builder) and 'bootstrap' (boot if not running), adding semantics that the schema omits. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with 'Inspect a builder instance,' a specific verb+resource statement. It also differentiates from sibling buildx_list by noting it provides human-readable detail for one builder while buildx_list returns machine-parsed JSON for all builders. This leaves no ambiguity about the tool's purpose.

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

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

The description explicitly contrasts with buildx_list for JSON output, effectively guiding the agent on when to use which tool. It also explains the bootstrap parameter's role ('Boot the builder if it isn't already running'). This provides clear context for selecting the tool and using its options.

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

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

Adds behavioral context beyond annotations: raises RuntimeError on CLI failure, parses from JSON format, and drops a truncated final record. This complements the readOnlyHint/destructiveHint annotations with factual execution details.

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

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

The description is short and front-loaded with the core action. It uses two sentences plus a returns bullet, with no redundant or filler content.

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

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

Given the simplicity (0 params, list operation), the description covers all essential aspects: return type, error behavior, truncation handling, and relationship to sibling tools. Annotations provide safety profile, completing the picture.

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

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

Tool has zero parameters, so there are no parameter semantics to clarify. The description does explain the return format and handling of truncation, but that's not parameter-related. Baseline 4 for 0 params is appropriate.

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

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

Description opens with 'List builder instances,' a specific verb+resource statement. It also distinguishes from siblings by naming buildx_inspect for one builder's human-readable detail and buildx_use for switching the default.

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

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

Explicitly states when to use this tool (machine-parsed view of every builder) and points to alternatives (buildx_inspect for detail, buildx_use to switch default), giving clear when-to-use and when-not-to-use guidance.

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

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

The description discloses critical behavioral traits beyond the annotations: it always passes `--force` because MCP lacks an interactive prompt, directly addressing the destructive nature. It also explains the return format. This adds significant value beyond the destructiveHint and idempotentHint annotations.

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

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

The description is well-structured and front-loaded: a one-line purpose, a prominent destructive warning, then a clean parameter list. Every sentence adds essential information, with no fluff or repetition of schema defaults.

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

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

Given the tool's complexity (7 parameters, nested objects, no output schema), the description is remarkably complete. It covers the return structure, warns about forced behavior, provides parameter examples, and mentions the companion tool buildx_du. Nothing critical is missing.

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

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

The input schema has no parameter descriptions (0% coverage), but the description compensates fully by documenting every parameter with concise explanations and concrete examples (e.g., filters as JSON, space values as strings like '10GB'). This gives the agent the semantic context needed to populate parameters correctly.

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

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

The description opens with 'Remove BuildKit cache entries.' This clearly states the tool's purpose with a specific verb (Remove), a specific resource (BuildKit cache entries), and differentiates it from sibling tools like buildx_du (which inventories disk usage) and buildx_remove (which removes builders).

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

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

The description provides a clear usage guideline by recommending 'Pair with buildx_du first to inventory what would be removed.' This tells the agent when to use this tool relative to a sibling. However, it does not explicitly discuss when NOT to use it or mention alternatives, so it stops short of a 5.

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

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

Annotations already mark destructiveHint=true, but the description adds crucial nuance: it deletes build cache unless keep_state=True, and it does not raise on non-zero CLI exit, requiring inspection of returncode/stderr. These are significant behavioral traits beyond the annotation.

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

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

The description is well-structured: a clear one-line summary, brief behavioral notes, an args list, and a returns format. Every sentence adds value, with no repetition or fluff.

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

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

Given no output schema, the description includes a precise return dict format. It covers side effects (cache deletion), error behavior (non-zero exit handling), and alternative tools, making it fully adequate for an agent to invoke the tool confidently.

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

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

Schema coverage is 0%, but the description compensates fully with an 'args' section explaining all 5 parameters, including the mutual exclusivity between name and all_inactive. Each parameter's meaning is clearly stated, adding value beyond the schema's type/default definitions.

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

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

The description clearly states the tool's function ('Remove a builder instance') with a specific verb and resource. It distinguishes from related tools by referencing buildx_create and explicitly pointing out the alternative buildx_prune for cache reclamation.

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

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

Provides explicit guidance on when to use this tool versus alternatives: 'use buildx_prune to reclaim cache while keeping the builder.' It also notes the tool deletes builders made by buildx_create, giving clear contextual usage.

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

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

The description reveals important behavioral nuances beyond the annotations: without flags the change is limited to the CLI session, 'default' persists for the current context, and 'global_default' persists across all contexts. It also warns about the impact of switching the global default and offers a non-switching alternative, giving the agent full understanding of side effects.

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

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

The description is well-structured and front-loaded with the core purpose. The scoping details, usage tips, and parameter explanations each add value without redundancy. The format is clear, and the returns section neatly summarizes the output regardless of the absence of an output schema.

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

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

With only three parameters, minimal annotations, and no output schema, the description covers everything an agent needs: purpose, scoping behavior, parameter meanings, return format, and explicit pointers to related tools. It is fully sufficient for correct invocation and decision-making.

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

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

The schema provides no descriptions for parameters (coverage 0%), but the description's 'args' section explains each parameter in detail: 'name' is the builder to activate (from buildx_list), 'default' persists for the current context, and 'global_default' persists across all contexts. This fully compensates for the schema gap.

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

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

The description opens with 'Select the active builder for subsequent buildx operations,' a specific verb and resource that clearly distinguishes this from siblings like buildx_list (which lists) and buildx_build (which builds). The scope is explicit: it changes the active builder for subsequent operations.

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

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

The description explains when to use this tool versus alternatives with concrete guidance: use buildx_list to see available builders, and avoid switching the global default by passing a specific builder name to buildx_build's builder parameter. It also clarifies the scoping semantics (session, context, global), providing clear conditions for each mode.

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

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

The description discloses key behavior beyond annotations: it does not raise on non-zero CLI exit, requires inspecting returncode/stderr, and notes that project_dir is copied to the target host if no local plugin. These are valuable operational details not covered by annotations.

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

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

The description is organized with an intro sentence, usage distinction, behavioral note, parameter list, and return type. Each section adds necessary information without redundancy, and the length is justified by the parameter documentation.

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

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

With 7 parameters, no output schema, and minimal annotations, the description covers all necessary aspects: what it does, how it differs from siblings, error handling, parameter meanings, and return format. It is fully complete for the tool's complexity.

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

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

Even though the schema has 0% description coverage, the 'args' section provides detailed semantics for all 7 parameters, including defaults, interpretation ('repeatable, -f', 'default: all'), and special behavior like project_dir copying. This fully compensates for the schema gap.

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

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

The description clearly states the tool builds images for a compose project, specifically those declared in `build:` sections, and distinguishes itself from `compose_up(build=True)` by noting it does not start anything.

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

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

It provides an explicit alternative (`compose_up(build=True)`) for build-and-start workflow, and clarifies the tool's purpose as build-only. The mention of non-zero CLI exit behavior also informs usage expectations.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable failure semantics: 'Does not raise on a non-zero CLI exit: on a failed render config may be None — inspect raw.stderr.' This goes beyond the structured annotations by explaining error behavior and return state.

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

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

The description is well-structured: a focused purpose sentence, usage guidance, failure behavior, then an args list and return specification. Every section earns its place and there is no filler or redundant restatement of the tool name.

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

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 fully specifies the return dict shape: config as str/dict/None, raw as CliResult dict, and the parsing behavior for format='json'. Combined with parameter coverage and annotations, this is sufficiently complete for an agent to invoke and interpret results.

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

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

Schema description coverage is 0%, but the description's args section compensates fully with concise one-liners for all six parameters, including useful details like project_dir default/copy behavior, files repeatability, services_only mapping to --services, and format behavior. This adds meaning beyond the raw schema.

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

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: 'Render the canonical compose configuration after merges, profiles, and variable substitution.' This clearly distinguishes compose_config as a read-oriented rendering/validation tool, not an operational Compose action like compose_up or compose_down.

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

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

It provides clear guidance: 'Use it to validate compose files and see exactly what the CLI will run before compose_up.' This gives a concrete when-to-use scenario, though it does not explicitly mention when not to use it or name alternatives to exclude.

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

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

The description discloses key behavioral traits beyond the minimal annotations, including error handling (no raise on non-zero exit, inspect returncode/stderr), the FileExistsError refusal for container-to-host copies, and RuntimeError for unsupported hosts. These are valuable details not available in annotations.

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

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

The description is long but information-dense, covering all essential caveats and alternatives without redundancy. The clear structure (summary, caveats, fallback behavior, args list) justifies the length, and every sentence serves a purpose.

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

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

The description covers return values, error modes, fallback behavior, and parameter semantics thoroughly. Even without an output schema, the returns dict is specified, making the tool's behavior fully understandable.

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

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

With 0% schema coverage, the description compensates by documenting each parameter's semantics in the args list (e.g., 'source - SERVICE:SRC_PATH or a host path', 'index - Container index when the service has multiple replicas'). This adds meaning beyond the bare schema.

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

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

The opening sentence clearly states the tool's function ('Copy files/folders between a service container and the server host's filesystem') and the description distinguishes it from related archive tools by explicitly naming alternatives.

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

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

The description provides explicit guidance on when not to use this tool (e.g., copying to stdout) and recommends alternatives (`container_archive_get`, `container_archive_put`, `container_archive_get_to_file`). It also explains the fallback to real CLI for ssh:// targets, making usage context clear.

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

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

Goes well beyond the destructiveHint annotation by specifying that images are kept, named volumes are only removed with the volumes flag, and that the tool does not raise on non-zero CLI exit (requiring inspection of returncode/stderr). These are non-obvious behavioral traits that an agent needs to know.

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

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

The description is well-structured: a clear opening line, a usage comparison, a key behavioral note, and a compact bulleted parameter list. Every sentence adds value and there is no redundancy; the length is justified by the number of parameters and the need to clarify destructive behavior.

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

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 explicitly documents the return format as a dict with returncode, stdout, stderr, and truncated. It covers all 7 parameters, the destructive semantics, and the error behavior, making the tool fully self-contained for an agent to use safely.

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

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

The input schema has 0% description coverage, but the description compensates fully by explaining every parameter: project_dir, files, project_name, profiles, volumes, remove_orphans, and timeout_seconds. Each parameter gets a concise one-line semantic explanation, which is critical for correct invocation.

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

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

The description clearly states 'Stop and remove containers, networks (and optionally volumes) for a compose project' and identifies it as the inverse of compose_up. It names the exact resource (compose project) and actions, making it easy to distinguish from sibling tools like compose_stop and compose_restart.

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

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

Provides explicit guidance: 'Use compose_stop to stop without removing anything' and notes that volumes are only removed with volumes=True. This clearly tells the agent when to choose this tool versus alternatives, which is exactly what usage guidelines should do.

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

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

Annotations only include readOnlyHint=false and destructiveHint=false, so the description carries the transparency burden. It discloses that `-T` is always passed (no TTY) and warns that `sh -c` interprets shell metacharacters in untrusted substrings. It also documents the return dict and timeout default, adding useful behavioral context beyond the schema.

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

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

The description is efficiently structured: a one-sentence purpose, two behavioral caveats, then a tidy parameter list. No wasted words, and all content is relevant to selecting and invoking the tool.

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

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

Given 10 parameters, a nested env object, and no output schema, the description covers return values, default behavior, multi-replica indexing, and shell-safety guidance. It provides a complete operational picture for an agent.

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

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

The input schema has 0% description coverage, but the tool description fully compensates by listing all 10 parameters with clear explanations, defaults, and special semantics such as `project_dir` copying and `index` for replicas. This is exactly the information an agent needs to fill parameters correctly.

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

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

The description opens with 'Run a command inside an already-running compose service container', which names a specific verb and resource scope. It also references `container_exec` as a related tool, helping to position this tool relative to a sibling.

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

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

The description makes clear this tool targets compose-managed service containers and mentions `container_exec` as an alternative, but it does not explicitly state when to prefer one over the other. It does give concrete execution guidance about using exec-form argv versus `sh -c` forms to handle shell metacharacters.

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

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

Annotations already declare `readOnlyHint: true` and `destructiveHint: false`, so the safety profile is covered. The description adds valuable behavioral details like raising RuntimeError on CLI failure and the nuance that `project_dir` may be copied to the target host if no local plugin. It does not contradict annotations.

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

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

The description is well-structured with clear sections (purpose, usage, args, returns). Every sentence adds value, though the 'Answers...' sentence slightly overlaps with the first line. It remains compact given the parameter details and contextual notes.

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

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

With no output schema and 0% schema param coverage, the description fully specifies parameters, return values, error behavior, and prerequisites. It also references related tools and edge cases (e.g., container existence, plugin copy behavior), making it complete for a read-only tool.

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

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

Schema description coverage is 0%, but the description compensates by documenting all four parameters with meaningful explanations: `project_dir` (default and copy behavior), `files` (repeatable `-f`), `project_name` (override), and `services` (restrict/default). It also explains the return format, making the parameters and output fully understandable.

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

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

The description clearly states the tool lists compose project service images, parsed via `--format json`. It distinguishes from sibling tools by specifying the exact question it answers ('what image and tag does each service container actually run?') and contrasts with `compose_ps` and `image_list`.

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

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

Explicit usage guidance is provided: when to use (to get actual image/tag per container), prerequisites (containers must exist via `compose_up`/`compose_create`), and alternatives (`compose_ps` for state, `image_list` for daemon-wide). This covers both when and when-not.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral details: immediate execution with no grace period, non-raising behavior on CLI errors, and the exact return shape (returncode/stdout/stderr/truncated). This significantly enriches the agent's understanding beyond what annotations provide.

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

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

The description is well-structured: a one-line summary, a usage alternative note, a failure-handling note, a compact args list, and a returns line. Every sentence carries necessary information, and the most critical usage guidance is front-loaded. No waste or redundancy.

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

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

With 6 optional parameters and no output schema, the description covers all bases: parameter meanings and defaults, return format, error behavior, and when to prefer an alternative. It provides a self-contained guide for invoking this tool correctly, making it fully contextually complete.

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

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

The input schema has zero descriptions (schema_description_coverage=0%), but the description's 'args' section thoroughly explains all six parameters, including defaults (e.g., services default all, signal default SIGKILL) and examples (SIGTERM, SIGHUP). It even notes the behavior of project_dir when no local plugin is present. This fully compensates for the missing schema descriptions.

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

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

The description uses a specific verb ('Send a signal') and resource ('compose project's containers'), clarifies the default signal (SIGKILL), and distinguishes itself from compose_stop by explicitly recommending the latter for clean shutdown. This makes the purpose unambiguous and distinct from siblings.

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

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

It gives explicit guidance on when to use this tool versus compose_stop ('prefer compose_stop for a clean shutdown'), and provides handling instructions for non-zero CLI exits (inspect returncode/stderr). This is strong, actionable usage guidance that covers both selection and error handling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral details such as raising RuntimeError on CLI failure and returning parsed JSON dicts per project. It also clarifies the 'all' parameter includes stopped projects, going beyond the bare schema.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Each line adds necessary information: purpose, scope, alternative, error behavior, parameter meaning, and return format, with no wasted words.

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

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

For a simple list tool with one optional parameter, the description is complete. It covers what the tool returns, how the output is parsed, the effect of the only parameter, error behavior, and how it relates to sibling tools, leaving no significant gaps.

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

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

The input schema has 0% description coverage, but the description fully explains the only parameter 'all' as 'Include stopped projects.' It also documents the return format ('list - One dict per project'), which compensates for the lack of schema descriptions and output schema.

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

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, specifying a project-level view with one entry per project. It distinguishes itself from compose_ps, which lists containers of a single project.

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

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

The description provides clear context for when to use this tool (listing projects at the project level) and explicitly references compose_ps as the alternative for viewing containers of a single project. It does not list extensive exclusions, but the guidance is sufficient for a simple listing tool.

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

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

Annotations only declare readOnlyHint=true and destructiveHint=false. The description adds crucial behavior: 'never follows', 'always returns promptly', 'Log text arrives on stdout', and especially 'Does not raise on a non-zero CLI exit — inspect returncode/stderr in the result.' This goes well beyond annotation hints and helps the agent interpret results correctly.

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

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

The description is well-structured: a leading summary paragraph front-loads the core behavior, followed by a compact arg list. Every sentence adds value—no filler. The parameter explanations are grouped logically and remain scannable despite covering 8 parameters.

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

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

The tool has 8 parameters, no output schema, and 0% schema description coverage, so the description must carry full weight. It does: it covers all params, return values (dict with returncode/stdout/stderr/truncated), failure behavior (non-zero exit not raising), and placement among siblings. This is fully adequate for an agent to select and invoke correctly.

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

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

Although schema description coverage is 0%, the description includes an 'args' block that explains every parameter with concrete meaning: 'project_dir - Dir with the compose file...', 'services - Restrict to these services...', 'tail - Lines per container (default 200), or the literal "all"...', etc. This fully compensates for the bare schema and supplies format hints for `since`/`until`.

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

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

The description opens with a specific verb+resource: 'Fetch a bounded slice of logs from a compose project (never follows).' It clearly distinguishes from sibling tools by name-checking `container_logs` and `service_logs` for other log sources, and the 'never follows' qualifier adds precision.

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

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

Explicit usage guidance is provided: 'For one container's logs use `container_logs`; for a swarm service use `service_logs`.' It also explains when this tool is appropriate ('bounded and non-following by design, so it always returns promptly'), giving the agent clear decision criteria.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false. Description adds substantial behavioral context: what happens to processes (frozen), what resources are retained (memory, network endpoints, state), and crucially the non-raising CLI behavior requiring returncode/stderr inspection. No contradiction with annotations.

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

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

First sentence states the core action. Second provides key trade-offs and alternatives. Third covers error behavior. Args list is concise and directly follows. Every sentence earns its place; no filler.

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

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

Covers purpose, usage distinctions, behavioral nuances (process freezing, resource retention), error handling, parameters with defaults, and return format (dict with returncode, stdout, stderr, truncated). No output schema exists, so the return description is sufficient. Complete for a compose control tool.

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

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

Schema has 0% coverage, but description includes an args section with clear semantics and defaults for all 4 parameters: services (restrict, default all), project_dir (default server cwd, remote copy note), files (explicit -f paths), project_name (override). This fully compensates for missing schema descriptions.

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

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

Description clearly states the tool pauses compose project containers ('Pause the containers of a compose project') and explicitly differentiates from siblings: resume with compose_unpause, stop with compose_stop, and stop+delete with compose_down. The verb and resource are specific.

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

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

Explicit guidance on when to use this tool versus alternatives, including semantic differences ('Paused containers stop consuming CPU but keep memory, network endpoints, and state') and direct references to compose_unpause, compose_stop, and compose_down. Also notes error behavior (does not raise on non-zero CLI exit) and how to inspect results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it explains the published=None case, the RuntimeError on CLI failure, and the exact return schema. It also notes project_dir is copied to the target host when no local plugin exists, which goes beyond annotation data.

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

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

The description is front-loaded with purpose, then organized into args and returns sections. Every line earns its place: parameter meanings, defaults, exceptions, and return semantics. It is detailed but not redundant with the schema.

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

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

For a tool with 7 params, no output schema, and no enum constraints, the description provides everything an agent needs to select and invoke correctly: purpose, alternatives, failure behavior, param semantics, and return structure. It is complete for safe, correct use.

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

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 full parameter burden. It does so thoroughly: each of the 7 parameters is named with meaning and defaults (protocol, index, project_dir, files repeatable, project_name override). The return dict is also fully documented.

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

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

The description opens with a specific verb 'Resolve' and resource 'host binding for a service's container port', clearly distinguishing it from container-level tools. It also frames it as 'The compose equivalent of `docker port`', which disambiguates it from sibling compose commands.

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

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

It explicitly states when not to use this tool: 'For non-compose containers read `container_inspect`'s NetworkSettings.Ports instead.' This gives a clear alternative and contextual boundary, which is exactly the kind of guidance needed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds critical behavior beyond that: 'Does not raise on a non-zero CLI exit: services comes back empty — inspect raw.stderr.' It also explains the return format and that output is parsed from `--format json`, giving the agent a full picture of what to expect.

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

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

The description is highly efficient: one sentence for purpose, one for differentiation, one for error behavior, then a concise args list and return type. Nothing is redundant; it front-loads the essential purpose and immediately distinguishes from siblings, making it easy to parse.

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

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 no output schema, the description is complete: it explains the return dict, the error behavior (empty services, inspect raw.stderr), and parameter defaults. It covers all necessary context for an agent to invoke it correctly and interpret results.

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

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 with an 'args' section that explains every parameter (project_dir, files, project_name, services, all). Each has a clear meaning and default, e.g., 'project_dir - Dir with the compose file (default: server cwd; copied to the target host if no local plugin)'. This provides complete semantic coverage.

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

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 containers in a compose project, parsed from `--format json`.' It clearly distinguishes from siblings by stating 'compose_list enumerates projects, and container_list covers non-compose containers.' This is a precise, unambiguous purpose.

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

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

The description explicitly names alternatives and when they apply: 'compose_list enumerates projects, and container_list covers non-compose containers.' It also provides behavioral guidance for error handling ('Does not raise on a non-zero CLI exit... inspect raw.stderr'), which helps the agent know when and how to use the tool.

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

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

With annotations only providing readOnlyHint=false and destructiveHint=false, the description carries the burden of behavioral detail. It states that containers are not started, explains the project_dir copying behavior for remote hosts, and mentions ignore_pull_failures semantics and timeout default. It does not contradict annotations and adds useful context, though it could elaborate on failure modes beyond the return dict.

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

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

The description is well-structured: a one-sentence purpose, then usage guidance, then a parameter list, then return value. Every sentence adds value—no filler. It is longer than average, but the added length is justified by the density of useful information.

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

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

Despite no output schema, the description includes the return dict format, which covers expected results. It also provides parameter details, alternatives, and prerequisites. For a tool with 6 parameters and no schema coverage, this description is remarkably complete and leaves no major gaps.

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

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 explain the 6 parameters. It does so: project_dir, files, project_name, services, ignore_pull_failures, and timeout_seconds each get a clear, schema-enriching explanation. This more than compensates for the lack of schema-level documentation.

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

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

The description opens with a specific action: 'Pre-fetch images for a compose project's services without starting them.' This clearly states the verb, resource, and scope, and distinguishes it from siblings like compose_up and image_pull by emphasizing the separation of pulling from startup.

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

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

The description gives explicit use cases ('stage images before an outage window', 'refresh cached images before compose_up', 'verify images are accessible without starting containers') and directly contrasts with compose_up --pull always, telling the agent when to prefer this tool. It also notes the prerequisite for registry-authenticated pulls (system_login).

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

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

The description discloses key behavioral traits beyond the annotations: it does not recreate containers or apply config changes, it stops then starts services, and it describes the SIGTERM/SIGKILL grace period controlled by stop_timeout_seconds. It also explains the project_dir behavior when no local plugin is present. The return dict is specified, which is valuable since there is no output schema. No contradiction with annotations.

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

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

The description is appropriately sized and well-structured. It starts with a clear one-sentence summary, then usage guidance, then an alternative, followed by a compact parameter list. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool has six optional parameters and no output schema, the description is remarkably complete. It covers the exact operation, when to use it, alternatives, all parameter semantics, the return format, and important behavior like SIGKILL and file copying. It is sufficient for an agent to select and invoke the tool correctly without further documentation.

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

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

The schema has zero descriptions for parameters, but the description provides a complete arg list with meaningful explanations for all six parameters: project_dir, files, project_name, services, stop_timeout_seconds, and timeout_seconds. This fully compensates for the absent schema descriptions and adds context like defaults and repeatability.

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

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

The description opens with a specific verb+resource: 'Stop then start services without recreating containers or applying config changes.' This clearly distinguishes compose_restart from compose_up, which handles config changes, by explicitly naming the alternative. The purpose is unambiguous and strongly scoped.

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

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

It provides explicit usage guidance: 'Use this to bounce a service (e.g. to pick up a runtime file change or clear an in-memory state).' It also gives a clear when-not-to-use direction: 'If the compose file has changed (new image, environment, volumes, ports) use compose_up instead.' This directly addresses alternatives and exclusion criteria.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral details beyond this: it always disables TTY, defaults to detached mode with container removal, and creates a new container for each run. It does not mention auth/error behavior, but the disclosure of the --rm default and the new-container semantics is significant and non-contradictory.

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

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

The description is well-organized: a one-sentence purpose, two sentences of behavioral context, a complete args list, and a return type. Every sentence adds value and there is no redundant or fluff content. The structure is front-loaded with the most important information.

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

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

With no output schema, the description specifies the return dict with fields (returncode, stdout, stderr, truncated). It covers all parameters, key behavioral defaults, and the MCP-specific TTY constraint. Minor gaps include not elaborating on what 'truncated' means or how detached mode affects stdout/stderr, but these are acceptable given the overall richness.

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

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

Despite 0% schema description coverage, the description contains a complete 'args:' section explaining all 13 parameters in meaningful terms. Examples include noting that command runs in exec-form unless a shell is invoked, project_dir is copied if no local plugin, and timeout_seconds defaults to 600. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a specific verb+resource: 'Run a one-off command against a compose service.' It also explicitly differentiates from compose_exec by stating that it starts a NEW container rather than running inside an existing one, making its purpose unambiguous.

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

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

The description gives clear behavioral context: always passes -T, defaults to detached with --rm, and explicitly contrasts with compose_exec. It implies the intended use case (one-off commands in a new container) but does not explicitly list alternative tools or say when not to use it, falling just short of a 5.

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

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

Annotations already signal readOnlyHint=false and destructiveHint=false. The description adds crucial behavioral context by noting it starts containers 'without recreating them' and that project_dir is 'copied to the target host if no local plugin.' It also documents the return dict, providing transparency beyond the annotations.

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

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

The description is compact and well-structured: one sentence for purpose, one for usage boundaries, and a terse arg/returns list. Every sentence earns its place, and the format is easy to scan.

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

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

Given the tool's moderate complexity, the description covers purpose, alternatives, all parameter semantics, and the return structure. It provides enough context for an agent to invoke compose_start correctly without needing external docs.

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

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 five parameters with defaults and semantics, e.g., 'project_dir (default: server cwd; copied to the target host if no local plugin)' and 'timeout_seconds (default 600s).' This adds meaning far beyond the bare schema.

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

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

The description opens with a clear statement of action and object: 'Start existing (stopped) containers of a compose project.' It explicitly contrasts with compose_stop and compose_up, making its unique scope immediately apparent and distinguishing it from siblings.

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

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

It explicitly states when to use this tool versus alternatives: 'Counterpart to compose_stop' and 'Use compose_up to (re)create containers from the compose file.' This gives direct, actionable guidance on tool selection.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds value by specifying exactly what happens: containers are not removed, and state survives so compose_start can restore them. It also notes that stop_timeout_seconds is passed as `--timeout`, disclosing a key behavior. It does not mention side effects like process termination inside containers, but that is implied by 'stop services' and the non-destructive guarantee.

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

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

The description is front-loaded with the main purpose and the key differentiator from compose_down. The args section is structured and includes defaults/explanations. Every sentence provides useful information with no redundancy or fluff.

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

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

Given the six parameters, zero schema coverage, and no output schema, the description provides everything needed to invoke the tool: it lists all parameters, their defaults, and the return dict shape (returncode, stdout, stderr, truncated). This is sufficient for an agent to select and call compose_stop correctly.

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

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

Schema description coverage is 0%, so the description fully carries parameter semantics. It explains all six parameters: project_dir (default and host copying if no local plugin), files (repeatable -f), project_name (override), services (default all), stop_timeout_seconds (grace period), and timeout_seconds (subprocess default 300s). This is complete and actionable.

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

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: 'Stop services in a compose project without removing their containers.' This precisely distinguishes compose_stop from its siblings, particularly compose_down and compose_start. The scope is clear: it stops services but preserves containers/networks/volumes.

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

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

It explicitly contrasts with compose_down: 'Unlike compose_down, containers/networks/volumes survive — use compose_start to bring them back.' This tells the agent when to choose this tool (when persistence of infrastructure is desired) and points to the sibling for the reverse operation. The parameter defaults and the fact that services defaults to 'all' further clarify usage context.

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

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

The description adds valuable behavioral details beyond the readOnlyHint and destructiveHint annotations: output is ps-style text (not JSON) read from stdout, and the tool does not raise on non-zero CLI exit (inspect returncode/stderr). This fully discloses the tool's observable behavior.

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

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

The description is well-structured: main purpose first, then output format, error behavior, parameter list, and return value. Every sentence contributes necessary information without restating schema defaults or annotations. Length is appropriate for the tool's complexity.

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

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

For a read-only tool with 4 parameters and no output schema, the description covers purpose, output format, error handling, parameter semantics, and return structure. It is self-sufficient for an agent to select and invoke the tool correctly, and it even mentions the alternative 'container_top'.

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

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

With schema description coverage at 0%, the description compensates by listing all four parameters with readable explanations. It adds meaningful semantics such as 'project_dir' being copied to the target host if no local plugin, and 'files' being repeatable via '-f', which are not evident from the schema.

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

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

The description begins with a specific verb+resource: 'Show the running processes of a compose project's containers.' It clearly distinguishes from related tools by noting the per-container equivalent is 'container_top' and by emphasizing compose project scope.

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

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

It provides context for use (compose project containers) and explicitly names 'container_top' as the per-container alternative. However, it does not explicitly contrast with the sibling 'compose_ps' or state clear when-not-to-use conditions, so it falls slightly short of full guidance.

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

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

With annotations already indicating a mutating but non-destructive operation, the description adds valuable context: it clarifies the resume-from-frozen behavior and the non-raising exit strategy. This goes beyond the annotations without contradicting them.

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

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

The description is efficiently structured: purpose first, then comparisons, then error behavior, then parameters, then return value. No fluff, though the args list could be slightly more concise; each sentence contributes useful information.

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

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

For a state-changing compose tool with 4 optional parameters and no output schema, the description covers the operation, alternatives, error behavior, parameter semantics, and return format. It leaves out prerequisites like project existence but that's inferable from context.

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

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

Schema has 0% description coverage, but the description compensates by explaining each parameter's purpose (services, project_dir, files, project_name) with defaults and special notes (e.g., project_dir copied to target host if no local plugin). This adds meaning beyond the bare schema.

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

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

The description uses a specific verb+resource structure: 'Unpause the containers of a compose project'. It clearly distinguishes from compose_pause (reverse) and compose_start (counterpart for stopped containers), making the purpose unambiguous.

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

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

Explicitly states when to use this tool versus alternatives: 'Reverse of compose_pause' and 'compose_start is the counterpart for stopped containers'. Also provides guidance on error handling (does not raise on non-zero exit) which informs proper invocation.

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

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

The description discloses important behavior: it always runs detached to avoid blocking the server, and explains the optional wait behavior. Annotations (readOnlyHint=false) align with the mutating nature of starting containers. The description adds transparency beyond the annotations by clarifying the detach behavior and how to ensure readiness.

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

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

The description is succinct and well-structured. It starts with a clear one-liner, then lists parameters in a consistent format without unnecessary verbosity. Every sentence adds value, making it easy to scan and understand quickly.

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

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

Given the tool's moderate complexity (10 optional parameters), the description covers all parameters and provides sufficient behavioral context. It also specifies the return format (dict with returncode, stdout, stderr, truncated). However, it does not elaborate on error handling or edge cases, but this is not essential for basic usage.

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

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

The schema has no descriptions (0% coverage), but the description compensates by explaining each parameter concisely. For example, 'pull' is explained as 'Pull strategy; omit to use each service's own pull_policy', and 'wait' is defined as 'Block until services are healthy'. This provides meaningful semantics for all parameters without relying on the schema.

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

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

The description clearly states the tool's purpose: 'Bring up a Docker Compose project, detached.' It distinguishes itself from sibling tools like compose_start by focusing on bringing up the project and explicitly mentioning the detached mode, which is a key behavioral difference.

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

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

The description provides practical usage guidance: it notes that the command always runs detached, suggests using 'compose_ps' to confirm services are running, and mentions the 'wait' parameter to block until healthy. This gives clear context on when and how to use the tool, though it could explicitly contrast with compose_start or compose_run for stronger differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it blocks until timeout, kills the subprocess on timeout (TimeoutExpired), returns exit codes on stdout, and notes the project_dir copy behavior. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with a clear one-sentence purpose, followed by usage notes and a structured args block. It's a bit long but every section earns its place—especially given the lack of schema descriptions. The formatting is clear and scannable.

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

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

For a medium-complexity tool with 5 parameters and no output schema, the description covers everything needed: purpose, usage context, parameter semantics, timeout behavior, and return value format. It even distinguishes from related tools. No critical information is missing.

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

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 with an args section explaining each parameter: services (required), project_dir (default server cwd, copied to target if no plugin), files (repeatable), project_name (override), timeout_seconds (default 300). This adds meaning that the schema alone lacks, and even covers nuance like the plugin copy behavior.

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

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

The description states precisely what the tool does: blocks until named service containers stop and returns their exit codes. It clearly identifies the resource (compose services) and the action (wait), and explicitly differentiates from sibling tools like container_wait and service_wait.

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

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

The description gives explicit guidance on when to use this tool: for one-shot/batch services, and warns about long-running services with timeout_seconds. It even names alternatives: 'For a single container use container_wait; for swarm services use service_wait.' This is exemplary usage guidance.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: requires a swarm manager, configs are not encrypted at rest, data must be raw bytes with encoding advice, and configs are immutable with a prescribed update process. It also describes the return dict structure, going well beyond the annotations.

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

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

The description is well-structured with a concise opening, purposeful explanatory sentences, a clear args section, and a returns line. Every sentence adds value—no fluff. Despite being detailed, it remains focused and scannable.

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

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

For a 4-param tool with no output schema, the description is complete: all parameters are explained, the return value is specified, usage context and constraints are covered, and the immutability workflow is fully described. It leaves no critical gaps for an agent to invoke the tool correctly.

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

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 documenting all four parameters: name (unique within swarm), data (raw bytes, encode strings), labels, and templating with an example format. This adds meaning far beyond the bare schema types.

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

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: 'Create an immutable Swarm config object', and immediately distinguishes itself from secret_create and config_remove by explaining configs are for non-sensitive files. This clearly states what the tool does and differentiates it from relevant siblings.

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

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

It explicitly says when to use this tool (non-sensitive config files) and when to use secret_create instead (credentials/keys). It also provides an update workflow: create a new config, update the service, then remove the old config with config_remove. This is explicit usage guidance with alternatives.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, but the description adds valuable context: swarm manager requirement, post-creation readability, and base64 encoding of Spec.Data. No contradictions.

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

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

Purpose is front-loaded in the first sentence. Every subsequent sentence adds essential context: preconditions, comparison to secrets, usage guidance, and return format. No fluff.

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

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

For a single-parameter, no-output-schema tool, the description covers prerequisites, usage, return value structure, and behavioral nuance. Fully sufficient for correct invocation.

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

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

Schema coverage is 0%, so the description carries full weight. It defines id_or_name as accepting 'id or name' and documents the return dict's structure (ID, CreatedAt, UpdatedAt, Spec fields). Adds clear meaning beyond the bare schema.

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

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

The description clearly states 'Get a swarm config's full inspect payload by id or name', which is a specific verb+resource+scope. It also distinguishes from config_list by noting 'use this to read one config's contents and metadata'.

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

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

Explicitly says 'Requires a swarm manager' and contrasts with secrets: 'Unlike a secret, a config's payload IS readable after creation'. It also directs users to config_list for enumeration, providing clear when-to-use vs alternatives.

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

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

Annotations already indicate a safe read operation, but the description adds important behavioral context: configs include base64-encoded Spec.Data unlike secrets, and a swarm manager is required. This goes beyond annotations and warns about data volume, improving transparency.

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

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

Three short, focused paragraphs front-load the core action. Every sentence delivers value—usage context, filter keys, return shape—with no fluff or redundancy.

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

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

Given the single parameter and no output schema, the description provides all necessary operational details: prerequisite, filter syntax, and return document structure. The agent can confidently invoke this tool without additional lookup.

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

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

The schema has zero description coverage for the 'filters' parameter. The description fully compensates by explaining the parameter's purpose, valid filter keys, and the default behavior when omitted.

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

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

The description opens with 'List swarm configs,' using a specific verb and resource. It distinguishes itself from config_inspect and config_remove, and notes the difference from secrets, making its purpose unambiguous among many sibling tools.

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

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

It explicitly states the prerequisite ('requires a swarm manager'), provides valid filter keys, and directs users to config_inspect for single-config lookup. This gives clear when-to-use and when-not-to-use guidance, including an alternative tool.

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

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

Beyond the annotations (destructiveHint=true), the description discloses that a swarm manager is required, the tool fails if services reference the config, and it is the final step in a config rotation flow. It also clarifies the return type (bool) and the condition for success, providing significant behavioral context.

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

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

The description is concise and front-loaded with a single primary purpose sentence. It then provides essential prerequisite and flow context, followed by a clear args/returns section. No wasted words; every sentence earns its place.

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

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

For a simple one-parameter destructive tool, the description covers the key aspects: what it does, prerequisites, failure conditions, and the argument meaning. It references config_create for the broader workflow, making it complete within the tool family context.

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

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

The schema provides only a string parameter named id_or_name with no description. The description adds semantic value by specifying that this is 'The config id or name,' clarifying that either identifier can be used. It also documents the return value, which is useful despite the output schema.

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

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

The description opens with 'Remove a swarm config,' a specific verb+resource that clearly distinguishes this tool from its siblings config_create, config_inspect, and config_list. It also adds context about being the last step of a rotation flow, reinforcing its unique role.

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

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

It states the requirement for a swarm manager and explicitly warns that removal fails while services still reference the config, advising to update or remove those services first. This provides clear when-to-use and when-not-to-use guidance, though it does not explicitly name alternative tools.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description discloses that bytes are returned in-band, that MCP base64-encoding creates a 32 MiB default cap, that exceeding it aborts with ValueError, and that the return is a dict with `archive` and `stat` keys. This is richer behavioral context than typical.

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

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

The description is well-structured and front-loaded: one sentence for purpose, one for usage guidance, then a compact argument list. Every sentence earns its place, and the format aids readability.

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

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

For a 3-parameter read-only tool without an output schema, the description covers purpose, usage, parameters, and return format. It also names the alternative for large paths, making the tool self-contained and sufficiently complete.

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

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

Schema description coverage is 0%, but the description compensates completely by explaining each parameter: `id_or_name` (container id/name), `path` (inside container), and `max_bytes` (abort if exceeded, default 32 MiB). It adds meaning far beyond the raw schema.

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

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

The description begins with a specific verb and resource: 'Retrieve a file or directory from a container as a tar archive, returned in band.' It clearly distinguishes this tool from the sibling `container_archive_get_to_file` by explicitly contrasting in-band vs. streaming to host path.

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

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

The description gives explicit guidance: 'For large paths prefer `container_archive_get_to_file`' and explains why (in-band bytes capped because MCP base64-encodes them). This provides a clear when-to-use and when-not-to-use directive with a named alternative.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral details: streams straight to disk with no in-band byte cap, file written by the server's user, '~' expansion, and refusal of existing files unless overwrite=True. This adds meaningful context not present in structured data.

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

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

The description is well-structured: it starts with a direct purpose statement, then gives rationale for use, then lists parameters in an organized block. Every sentence adds value—no filler or redundancy—striking an excellent balance between completeness and efficiency.

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

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

Given the tool's moderate complexity and lack of output schema, the description covers all critical aspects: what it does, when to use it, behavior around file overwrites and path expansion, and the return value structure. It is self-sufficient for an agent to invoke correctly.

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

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 providing clear one-line meanings for each parameter: id_or_name, path, dest_path, and overwrite (including default behavior). This gives the agent complete understanding of expected inputs beyond bare schema types.

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

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

The description begins with a clear verb ('Retrieve') and specific resource ('file or directory from a container as a tar archive written to a file on the server host'). It immediately distinguishes itself from sibling tools by noting it is the 'File-writing variant of container_archive_get' and contrasts with 'container_export' for whole filesystem use.

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

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: 'prefer it for anything large, since in-band bytes are base64-encoded by MCP'. It also provides a clear alternative for a different use case: 'For the whole filesystem use container_export'. This gives decisive guidance on selection among related tools.

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

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

Annotations only convey readOnlyHint=false and destructiveHint=false, so the description carries the burden. It adds valuable behavioral details: from_file is read by server's user, ~ expansion, streaming to daemon, base64 encoding of in-band data, and the path must already exist. It does not mention overwrite semantics or error cases, but overall is transparent.

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

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

The description is well-structured: a concise summary, then additional context, then a clear args block. Each sentence adds value, and the formatting aids readability without unnecessary verbosity.

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

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

The description covers the tool's core behavior, parameter constraints, and return type, and references the inverse operation. It lacks explicit explanation of error handling when both/neither of data/from_file is provided, but overall it is sufficiently complete given the output schema and annotations.

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

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

The 'args' section explains every parameter beyond the schema, describing id_or_name as container id/name, path as requiring existence, data as tar bytes, and from_file as a server host path. It also clarifies the 'exactly one' constraint, fully compensating for the 0% schema description coverage.

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

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

The description clearly states the tool's function: 'Upload a tar archive to a path inside a container' with specific verb and resource. It also distinguishes itself as the 'Inverse of container_archive_get', differentiating it from sibling tools.

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

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

The description provides concrete guidance on when to use each input mode ('preferred for large archives' for from_file) and enforces the mutual exclusivity of data/from_file. It implicitly contrasts with container_archive_get but does not explicitly list exclusion scenarios or alternatives.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important runtime behavior: 'The container is paused by default during the snapshot to ensure filesystem consistency — set `pause=False` only if the container cannot be paused.' It also explains the `changes` semantics and states the return value is the full inspect payload containing the new image id. No annotation contradiction exists.

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

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

The description is compact and front-loaded with the core purpose. The first sentence defines the action, the second gives use cases and alternatives, and the third explains pause behavior. The args list is terse but informative, with each parameter receiving a short meaningful phrase. No filler or redundant content is present.

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

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

This is a complex 8-parameter tool with no output schema. The description covers all parameters, explains the pause default and exception, describes the `changes` input format, and states the return type ('dict - The new image's full inspect payload'). It provides enough context for an agent to invoke the tool correctly without additional documentation.

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

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

Although the input schema has no parameter descriptions (0% coverage), the description's dedicated args list explains every single parameter: id_or_name, repository, tag, message, author, pause, changes, and conf. It even gives an example Dockerfile instruction format for `changes`. This fully compensates for the schema's lack of descriptions.

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

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

The description opens with a specific, unambiguous verb phrase: 'Snapshot a container's current filesystem state as a new image.' It clearly identifies the resource (container) and the outcome (image). The description also differentiates from sibling tools by explicitly recommending `image_build` for repeatable builds, which distinguishes this ad-hoc snapshot workflow from declarative image creation.

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

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 the tool: 'Useful for capturing a debugging state or saving manual changes made inside a container.' It also gives concrete alternative guidance: 'For repeatable builds use `image_build` with a Dockerfile instead; publish the result with `image_tag` + `image_push`.' It additionally explains when to disable pause, giving a clear if-then usage rule.

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