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

The annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds useful behavior: the three categories with their usability, the case-insensitive substring filtering behavior of 'query', and a pointer to get_guides('resources') for details. This goes beyond the annotations by explaining what the list contains and how filtering works, 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 well-organized with a numbered list for the three resource categories, a clear 'Call it to...' sentence for usage timing, and a brief note about the query parameter. Every sentence contributes meaning; there is no redundancy or filler. The key purpose is front-loaded, and the 'Read-only. Details: get_guides('resources').' coda is a compact pointer. This is appropriately sized for the amount of information conveyed.

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

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

For a tool with only two parameters (one required), no output schema, and annotations covering the safety profile, the description is complete. It gives the purpose, usage timing, parameter semantics, and even a fallback for deeper details (get_guides). The absence of a detailed return format is acceptable because the tool's purpose is clear and the read-only annotation reassures the agent; an output schema is not present, so the description does not need to explain it, but it does enough to enable 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 description coverage is 0%, so the description must carry the burden. It thoroughly explains the 'query' parameter ('case-insensitive substring over names, descriptions, types, and env var names') and its purpose. The 'projectId' parameter is not explicitly described, but the opening line ('a project's code') makes its role obvious. The description compensates well for the lack of schema detail.

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 verb 'List' and the resource ('env vars a project's code can use and the resources behind them'), then enumerates three specific categories. It distinguishes itself from siblings like provision_resource and request_external_resource by explicitly saying to call it before provisioning or requesting any credential. This is a specific, 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?

Explicit guidance is given: 'Call it to learn what env vars exist before writing backend code, and BEFORE provisioning or requesting any credential (the owner may already have the one you need).' This tells the agent when to use this tool and implicitly when not to (i.e., before provisioning/requesting). It also explains the query parameter's filtering use case. No alternative tools are named, but the timing and rationale are unambiguous.

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