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

With no annotations supplied, the description carries the full burden and largely succeeds: it names the matching semantics used (root-anchored, last match wins, ** crosses dirs) and explains the real consequence of a bad ignore file ("the build would fail or silently omit them"). What it does not state is whether the tool is purely read-only and whether a missing path is reported as a finding or an error.

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?

One dense sentence front-loads the resource and the failure modes, then a second sentence supplies the matching rules. Every clause carries information, though the parenthetical list is long enough that a reader must parse carefully; a short bulleted breakdown would scan faster.

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?

An output schema exists, so return values need no explanation, and the description covers the check surface, the matching semantics, and the stakes of a bad result. For a single-parameter read-check tool this is effectively 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 coverage is 0% — the only parameter is titled "Path" with no description. The description partly compensates by clarifying that the path may be a Dockerfile or a directory, which is genuinely useful disambiguation, but it does not say whether relative paths are resolved from cwd or how a directory is located/disambiguated.

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

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

States a specific verb and resource ("Check the .dockerignore") and enumerates exactly the four classes of problem it detects: missing file, missing .git/node_modules/.env exclusions, nested node_modules missed by root-anchored patterns, and patterns that exclude COPY'd files. This is clearly distinct from siblings like lint_dockerfile or dockerfile_overview, which operate on the Dockerfile itself.

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

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

The description implies the context of use ("for a Dockerfile (or a directory)") and hints at the build-failure consequence that motivates running it, but it never states when to prefer this tool over lint_dockerfile or fix_preview, nor any prerequisites. Usage is inferable rather than directed.

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

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

No annotations are supplied, so the description carries the full burden; it discloses that the operation is a read-only summarization over a local file and lists the specific artifacts returned, including the exec-vs-shell-form distinction. It does not discuss failure modes (e.g., path not found, file that is not a Dockerfile) or permission expectations, which is a modest gap for an inspection tool.

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

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

Three sentences with a clean progression: what is produced, when to reach for it, then how to call it. The field enumeration is dense but every item listed is a distinct output the agent would otherwise have to discover, and nothing is redundant with the schema or annotations.

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?

An output schema exists, so the description is not required to document return values, yet it usefully summarizes them anyway; the sole parameter is fully explained. The remaining gap is that it does not clarify how this differs from explain_layers, the closest sibling, which an agent would have to infer.

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

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

Schema coverage is 0% — the schema only declares `path` as a string with no description — so the sentence "`path` is a Dockerfile or a directory containing one" is genuinely load-bearing, telling the agent that a directory is acceptable and that discovery happens internally. It does not cover relative-vs-absolute resolution or symlink behavior, so not a perfect 5.

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 ("Summarize a Dockerfile") and then enumerates exactly what is extracted: stages with base images, layer count, exposed ports, final user, workdir, and ENTRYPOINT/CMD with exec vs shell form. This is enough to distinguish it from lint_dockerfile, explain_layers, and suggest_multistage without opening any schema.

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 sequencing guidance: "Start here to understand a file before linting it," which positions it relative to lint_dockerfile as a prerequisite step. It does not explicitly say when to prefer explain_layers or suggest_multistage instead, so sibling differentiation is only partially covered.

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

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

With no annotations, the description carries the full burden and does meaningful work: 'Sizes are estimates' sets accuracy expectations and 'nothing is built' discloses that the tool is a safe, side-effect-free static analysis. It also enumerates the specific defect classes it reports, so the agent knows what the output covers; it does not discuss error behavior for a missing/invalid path.

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?

One dense sentence, front-loaded with the core purpose before the heuristic and order-problem details. The four-item parenthetical is long but each example earns its place by concretizing what 'ORDER problems' means; a brief split into two sentences would read slightly better.

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?

An output schema exists, so return values need not be described, and the description adequately covers scope, accuracy caveats, and defect classes for a single-input analysis tool. The remaining gap is practical: no indication of what 'path' should contain or what happens when it does not resolve to a Dockerfile.

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% for the single required parameter 'path', and the description never mentions it or says whether it points to a Dockerfile, a directory, or a build context. The one parameter the agent must supply is left entirely to inference, which is the opposite of compensating 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 a specific verb and resource: 'Explain which Dockerfile instructions create image layers,' and adds two concrete outputs (heuristic size hints and ORDER problems). That is clearly distinct from dockerfile_overview or lint_dockerfile in framing, but it never explicitly names an alternative, and 'list ORDER problems' overlaps enough with lint_dockerfile that an agent might hesitate between the two.

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?

Usage is only implied: the listed pathologies (COPY . before dependency install, cleanup in a later layer, recursive chown after COPY, volatile build args) suggest when the tool is valuable, and 'nothing is built' signals a static-analysis context. There is no explicit when-to-use/when-not statement and no routing away from lint_dockerfile or fix_preview, so the agent must infer the choice.

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

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

With no annotations supplied, the description carries the full burden and mostly succeeds: it explicitly declares the tool is non-mutating ('Never writes the file') and describes exactly which transformations will appear in the diff. It also discloses a secondary output (findings that need manual changes), though it does not cover failure behavior, e.g. what happens if path does not exist or is not a Dockerfile.

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 non-mutation guarantee is stated up front and the fix list is compactly parenthesized. The enumeration is long but each item earns its place by telling the agent what the diff will contain; only slight tightening would improve it.

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-argument tool with an output schema, the description covers purpose, mutation safety, and output nature (diff plus manual findings) adequately. The one material hole is the ambiguity of 'path', which is unaddressed in both schema and description.

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?

Only one parameter exists, 'path', and the schema gives it zero description coverage. The description never clarifies whether it is a path to a Dockerfile, to a directory, or to a compose/Dockerfile pair, so it adds no meaning beyond the bare schema field.

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

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

States a specific verb and resource: it shows a unified diff of safe automatic fixes for a Dockerfile, and enumerates the exact fix categories (apt-get flags, ADD->COPY, MAINTAINER->LABEL, etc.). The scope is unmistakable, but it never names or contrasts itself with the closest sibling, lint_dockerfile, which also reports Dockerfile problems.

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

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

The description implies the workflow ('Never writes the file: apply the diff yourself') and hints at a two-stage process by saying it also lists findings needing manual changes. However, it gives no explicit when-to-use versus lint_dockerfile or when-not guidance, leaving the agent to infer that lint_dockerfile diagnoses and fix_preview produces a patch.

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

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

With no annotations, the description carries the full burden and does meaningful work: it states that secret values are never echoed, that parsing uses yaml.safe_load only (no execution risk), and that findings can be suppressed via a '# dockerlint-ignore: DCxxxx' comment. It does not describe failure behavior for a missing or unreadable path, which is the remaining gap.

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

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

The verb and resource are front-loaded, and the long rule enumeration is genuinely scoping information rather than filler, followed by a compact suppression hint. It is dense but every clause carries content; only the rule list could arguably be trimmed.

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?

An output schema exists, so return values need not be explained, and the description covers safety posture, rule coverage, and suppression. What is missing is the meaning of the required 'path' argument and any error-handling note, which matters for a single-required-param 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% — the single 'path' parameter has no description in the schema — and the tool description never clarifies it either. An agent cannot tell whether 'path' means the compose file itself or a directory to scan, nor whether relative or absolute paths are accepted, so the description fails to compensate for the coverage 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 a specific verb and resource ('Lint a docker-compose / compose.yaml file') and then enumerates the exact rule set (DC2001-DC2014) it applies. This makes it immediately distinguishable from the sibling 'lint_dockerfile', which targets a different artifact.

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 scope is clearly bounded to compose.yaml files and the enumerated checks tell an agent what situations the tool covers, so the choice versus lint_dockerfile is inferable from the resource named. It stops short of explicitly stating when not to use it or naming alternatives, which keeps it out of 5 territory.

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

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

With no annotations supplied, the description carries the full burden and does well: it discloses 'Never builds anything' (a clear safety/read-only signal), that secret values are never echoed, and that findings include severity and a concrete fix. It stops short of stating failure modes, e.g. behavior on a missing/non-Dockerfile path.

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

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

Front-loaded with purpose and scale, then a dense rule summary and the suppression mechanism. The long rule enumeration earns its place by telling the agent exactly what classes of findings to expect, though it could be trimmed slightly.

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?

An output schema exists, so return values need not be re-explained, and the description still summarizes finding structure (rule ID, severity, line, explanation, fix). Combined with the safety note and suppression syntax, an agent has everything needed except explicit `path` semantics.

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% and the single `path` parameter is never described — it is ambiguous whether it expects a Dockerfile file path or a directory containing one. The verb 'Lint a Dockerfile' weakly implies a file path, so some meaning leaks through but not enough to compensate for the coverage 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?

States a specific verb and resource ('Lint a Dockerfile') plus concrete scope ('28 rules, DL1001-DL1028'), which cleanly separates it from the sibling lint_compose. An agent can identify this as the Dockerfile-specific linter without opening the schema.

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?

Usage is implied by the resource name, and the description usefully documents the in-file suppression syntax (`# dockerlint-ignore: DL1003`). However, it never states when to prefer this over siblings like fix_preview or suggest_multistage, nor any prerequisites or exclusions.

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

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

With no annotations, the description carries the full load and does well: it declares a non-mutating contract ('never writes a file'), describes what is preserved from the original (base image version, workdir, ports, CMD/ENTRYPOINT), and says it explains what moves to the build stage. It omits failure behavior for already-multi-stage or unrecognized files.

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 sentences, front-loaded with the output contract, then capability, then value. Every sentence carries information; the ecosystem list is slightly padded but genuinely useful for deciding applicability.

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?

An output schema exists, so return values need no explanation. For a one-parameter read-only tool the description covers scope, output form, and preserved settings; only edge-case behavior and the exact meaning of 'path' are 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 single 'path' parameter has 0% schema description coverage, so the description should say it points to the Dockerfile to analyze. 'A single-stage Dockerfile' only weakly implies that; an agent could plausibly pass a directory path instead.

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

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

States a specific verb and resource ('Propose a multi-stage rewrite of a single-stage Dockerfile') and pins down the output form ('as TEXT, never writes a file'). It does not name a sibling to contrast with, so the agent must infer the boundary against fix_preview or lint_dockerfile on its own.

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 input constraint ('single-stage Dockerfile') implies when the tool applies, but there is no explicit when-not guidance, no prerequisite statement (e.g. file must exist and be readable), and no named alternative for already-multi-stage or non-Python/Node/Go/Rust files.

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