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

With no annotations provided, the description carries the full burden and does so well: it discloses the underlying commands (git check-ignore, git ls-files, git log --all), the read-only guarantee ('no content is read, no history is rewritten'), the name-only matching scope, and the environmental prerequisite (git on PATH). That is exactly the behavioral context an agent needs before invoking it.

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 single dense paragraph is front-loaded with the scoping question, then works through verdicts, mechanism, safety guarantees, and prerequisites in a logical order with no filler. The trailing 'path: folder inside the repository to check.' line is tacked on awkwardly rather than integrated, which costs a point.

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-value shape need not be explained, and the description covers everything else: what is checked, which files are excluded, what the possible outcomes are, what side effects are absent, and what runtime dependency must exist. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 0% for the single parameter, but the description compensates by explaining that path is 'folder inside the repository to check', which clarifies it is scoped to the repo rather than an arbitrary filesystem path. It does not restate the default of '.', but the added meaning is sufficient for a one-parameter tool.

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

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

The description opens with a precise framing question and then names the exact resource set (.env/.env.* files, templates excluded) and the three verdicts it returns (ignored, tracked, present in any commit). It also calls out the history-deleted case and the ignored-template flag, which no sibling (env_overview, validate_env) covers, so an agent can tell it apart without reading schemas.

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

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

The use case is strongly implied by the framing question 'Is each real env file safe from git?', which tells an agent this is the git-hygiene check. However, no sibling is named and there is no explicit 'use this instead of env_overview/validate_env when X' routing guidance, so the selection logic must be inferred from the sibling names alone.

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 well: it discloses the exact classes of findings, the `# optional` exemption rule, and that commented-out `# NAME=` lines count as documented. It does not state read-only/side-effect status or how `# optional` interacts with duplicates and type mismatches, leaving some behavioral gaps.

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

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

Front-loaded with the core comparison, then the finding types, then parameter modes — a logical order with no filler sentences. The inline "path: ... file / against: ..." block is slightly compressed and reads awkwardly, but nothing is wasted.

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-value detail is rightly omitted, and all three parameters plus the finding categories are covered. The remaining gap is the undefined notion of an "env root" and scan scope, which an agent needs to predict what `path` will cover.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: `path` is the folder to scan, `file` and `against` are specific env files relative to `path`, with a worked example. It does not clarify what an "env root" is or whether the scan recurses, which matters for `path` semantics.

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 first sentence names a specific verb and resource — compare .env against its template (.env.example/.sample/.template) across every env root — and the following sentence enumerates exactly what the comparison reports (missing names, extras, empty-but-required, duplicates, type mismatches). This is clearly distinct from siblings like validate_env or generate_example.

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 distinguishes the default whole-tree scan from the targeted two-file mode via file/against, with a concrete example (file=".env.production", against=".env.example"). It stops short of saying when to prefer this over validate_env or what happens if no env roots are found, so it lacks explicit alternatives/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 behavioral burden and does well: it discloses the discovery set, that results are grouped by env root (multiple in a monorepo), the categories of findings (counts, duplicates, syntax problems, BOM/CRLF, client prefixes), and the key privacy guarantee 'Never shows values'. It omits any sandbox-escape/error behavior for paths outside the sandbox, which keeps it from a 5.

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 first sentence declares scope, the long second sentence enumerates sources and findings, and the final clause plus parameter note make it front-loaded and actionable. It is dense but each clause adds information; the enumeration is long though justified for this 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?

An output schema exists so return shape needn't be explained, and the description still covers scope, sources scanned, grouping behavior, reported finding types, non-disclosure of values, and the sandbox semantics of the single parameter. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0% for the sole parameter, so the description must compensate, and it does: it explains that path is relative to the server's --dir sandbox and that the default ('.') scans the whole sandbox. That is meaningful context the bare schema string 'Path' does not convey.

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

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

States a specific verb and resource ('Map every environment-variable source under a folder') and then enumerates exactly which sources it finds (.env, .env.local, .env.<environment>, templates, docker-compose environment:/env_file:, CI workflow env: blocks). It distinguishes itself from siblings by being the breadth-first scanning tool ('Start here').

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 closing 'Start here' explicitly positions it as the entry point before the sibling tools (compare_env, find_usage, validate_env, check_gitignore, generate_example), which is real routing guidance. It does not name when-not to use it or which sibling to pick afterwards, so it falls 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?

With no annotations, the description carries the full behavioral burden and does so well: it names what it reports (undocumented reads with file:line, documented-but-unread, client-exposed secrets) and what it ignores (PATH, HOME, NODE_ENV, GITHUB_*), and it discloses two real limitations of the text-scan approach (reads in comments count; dynamic names like process.env[name] are invisible). The remaining gap is that it never says which template(s) form the baseline or that the operation is read-only.

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 purpose is front-loaded in the first sentence, which is good. However, the long enumeration of roughly a dozen env-access syntaxes across many languages is a token-heavy laundry list that could be compressed into a statement of ecosystem breadth without losing decision-relevant meaning.

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?

Because an output schema exists, the description need not explain return values, and it still explains the report categories and scan limitations well. The one material omission is how 'the templates' are located — that precondition is central to interpreting the cross-check results and is not stated anywhere.

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 parameter has 0% schema coverage, so the description must compensate, and the line 'path: folder to scan, relative to the sandbox' adds the resolution constraint (relative to sandbox root) that the schema's bare string type does not convey. It does not mention the '.' default, but the key semantic is covered.

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: 'Scan source code for environment reads and cross-check them with the templates.' An agent can tell this is a static code scan rather than a diff or validation tool, but no sibling is named, so the boundary with env_overview or validate_env is left to inference.

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: it reports undocumented/never-read/client-exposed variables, which suggests when the scan is useful. There is no explicit 'use this when' statement, no condition that selects it over compare_env or validate_env, and no stated prerequisite such as which template file is used as the baseline.

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 substantial work: nothing is written to disk, every line is emitted as empty `NAME=`, no values are ever included even from templates, and secret-exposure-to-browser cases get a warning. Missing only secondary details such as behavior on an unreadable or missing path or scan cost on large repos.

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 key guarantee (safe, empty-value text output) is front-loaded in the first sentence, followed by the content spec and the no-disk-write caveat. Structure is good; the trailing 'path: folder to scan.' line is a slightly tacked-on fragment rather than integrated prose.

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 need not explain return values, and it instead specifies the output's invariant shape (empty `NAME=` lines, per-root sections) plus warnings. For a single-parameter read-only generator this is nearly complete, with only path-resolution and failure-mode behavior unstated.

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% for the single parameter, so the description must compensate. It defines 'path' as the 'folder to scan', which adds real meaning beyond the bare string, but leaves open whether the scan is recursive, how relative paths resolve, and what the default '.' covers.

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 names a specific verb and artifact: 'Propose a safe .env.example as text', scoped to 'one section per env root'. That is clearly distinct from validate_env or compare_env, but it never explicitly names a sibling or states the boundary, so it stops short of a 5.

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: an agent can infer this is the tool for producing a starter example file, and the 'nothing is written to disk; paste or save the text yourself' line hints at the workflow. There is no explicit when-to-use/when-not guidance and no reference to the sibling tools that cover the other .env tasks.

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 it discloses the key non-obvious behavioral guarantee: no secret value is ever printed, making this effectively a safe read. It also reveals deeper checks (localhost URLs in production files, real-looking secrets in templates, browser-exposed prefixes) that an agent could not guess from the name. It omits whether the scan is recursive or how findings are reported, though an output schema 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 lead sentence is front-loaded with the purpose and the no-print guarantee before the check inventory. The inventory is a dense wall of semicolon-separated flags, but every item describes a distinct detectable condition rather than restating the 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?

The brief matches the tool's low complexity: two optional parameters are both explained, the privacy behavior is stated, and the categories of findings are enumerated while the output schema handles return shape. The only real gap is scan scope (recursive vs top-level) and how path/file interact when both are given.

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

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

Schema description coverage is 0%, so the description must compensate, and it does define both parameters in the trailing lines: 'path' as the folder to scan and 'file' as a single env file relative to 'path'. That covers the parameters but adds no detail on formats, defaults, or what happens when both are supplied.

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

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

The description states a specific verb and resource ('Check env files for mistakes') and narrows it with 'from names and shapes only (no value is ever printed)', which an agent can read as the core promise. The long list of checks further pins down what 'mistakes' means. It never names a sibling (env_overview, compare_env) for contrast, so the boundary with them is left to inference.

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 clarifies how the two parameters divide the work — 'path: folder to scan' versus 'file: validate only this env file (relative to path)' — which implies the two usage modes. It gives no guidance on when to prefer this over compare_env or env_overview, and no exclusions or prerequisites.

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