Request a secret from the user

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

With no annotations present, the description carries the full burden and does real work: it names the dialog fallbacks, the three storage destinations, and the key safety property that the value never enters the conversation. What is not disclosed is failure/cancel behavior, whether an existing value is overwritten, and what the call returns — meaningful gaps for a tool that writes to .env or a keychain.

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 dense sentences, front-loaded with the action and mechanism before the storage and follow-up guidance. Slightly redundant: 'never enters the conversation' and 'never ask the user to paste secrets in chat' restate the same safety idea, costing a clause.

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 three-parameter, annotation-free tool with no output schema, the description covers the workflow, storage destinations, and post-call usage well enough to invoke correctly. It leaves open what the tool returns on success and how it behaves if the target CLI (e.g. op) is unavailable, which matters given there is no output schema to fall back on.

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%, so the description must compensate. It partly does: the prose '(.env in the working directory, the OS keychain, or 1Password)' maps the target enum values to real destinations, and 'process.env.NAME' hints at the uppercase env-var naming pattern enforced by the schema. However, the `description` parameter is never explained (presumably the dialog prompt text), leaving one of three parameters undocumented anywhere.

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 (collect a secret from the user) and immediately names the concrete mechanism: a native password dialog with a stated fallback chain. It is unambiguous what calling the tool accomplishes, and nothing about it overlaps with a generic prompt or shell tool.

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 gives a clear trigger (you need an API key or secret) and an explicit prohibition ('never ask the user to paste secrets in chat'), plus a follow-up instruction to reference the value indirectly. It stops short of saying when not to use it — e.g. what to do if the secret already exists in the target — so it is clear context without full exclusion rules.

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