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

Adds substantial behavior beyond the annotations: consumption of one use, a five-minute maximum lifetime, one live link per person where a new link replaces an unused one, and the requirement for an approved secrets.use grant. The annotations only declare non-read-only, non-idempotent, non-destructive; the consequences and side effects here come entirely from the description.

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 and precondition are front-loaded in the first sentence, and every subsequent sentence adds a non-obvious constraint (single use, expiry, shell execution, replacement policy). No filler or restatement of 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?

With no output schema, the description appropriately explains what is returned (a link and a ready command) and carries the full safety and lifecycle story for a non-idempotent, use-consuming operation. The gap is the near-total silence on the input parameters, particularly the required identifiers.

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% across eight parameters, and the description only adds meaning for a few: dest (defaults to .env.local), expires_in (capped at five minutes), and loosely shell (run in the local shell). The two required parameters, project_id and binding_id, plus name, format, and result_offset receive no explanation in either the schema or the description.

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: obtain a one-use link plus a ready-to-run command that writes the secret value into a local file. It also scopes the precondition (key must have local_use true in read_references) and distinguishes this from any sibling that would return the value in-band.

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?

Gives explicit when-to-use (key marked local_use true, approved secrets.use grant) and strong when-not guidance ('never fetch the link with a tool whose output comes back to you', 'never print or read the file'). It does not name the alternative siblings (use_secret / export_secret) for the case where the key is not locally usable, so routing against those is left to inference.

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