Save one-time secret to a Vercel env var

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

Annotations only supply destructiveHint=true; the description adds the material context: the link is one-time and gets consumed, Vercel access is verified before consumption (a fail-safe ordering the agent would otherwise have to guess), auth comes from `vercel login` or VERCEL_TOKEN, and the var is written as type sensitive. This is consistent with, and additive to, the destructive hint.

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 short sentences, front-loaded with the core action, then the security property, then the auth/ordering behavior, then the alternative. No filler sentences.

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 7-param mutation with no output schema and thin annotations, the description covers the critical unknowns (auth source, pre-check ordering, secret exposure). What it leaves out is what happens on overwrite—whether an existing env var of the same key is replaced or rejected—which matters for a destructiveHint=true 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 coverage is 71%, so cwd/key/team/project/targets are already documented upstream. The description adds no parameter-level detail beyond restating the link's role—it never mentions key, targets, team, project, cwd, or passphrase semantics (e.g., whether passphrase is required for protected links).

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 chain and resource: open an ncrypted link and write its value into a Vercel project environment variable of type sensitive. This clearly separates it from ncrypted_read (which would surface the secret) and from ncrypted_to_dotenv (a different sink).

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?

Explicitly says 'Prefer this over reading a secret and running `vercel env add`', naming the alternative workflow and the condition that selects this tool. Combined with the 'never appears in this conversation' rationale, an agent knows exactly when to route here versus reading the link.

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