find_usage

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.