Unlock the vault

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

readOnlyHint=true declares the tool does not modify its environment, but the description explicitly describes a state change ('unlocks hidden chats for a few minutes'). The description also adds genuinely useful behavior (auth happens on the user's device, up to 2-minute wait), but it directly contradicts the annotation's read-only claim, so the contradiction rule applies.

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?

Four short sentences, each front-loaded with an actionable fact: effect and duration, then authentication channel, then the security constraint, then the timeout. Nothing is padded or redundant.

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 single-parameter, no-output-schema tool, the description covers the observable outcome, the authentication channel, the security constraint, and the wait bound. The one thing it leaves ambiguous is how the agent should behave if the unlock times out or fails, but that is a minor gap.

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 100% with a documented enum and default, so the schema already carries the parameter meaning. The description adds indirect value by describing what the auth flow does (Touch ID prompt vs. browser passphrase page), but it never names or explains the 'method' parameter or the 'link' option, so it does not meaningfully exceed the baseline.

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 (unlocks hidden chats) plus the scope of the effect ('for a few minutes'), which is the key differentiator from lock_vault and from read_hidden/list_hidden. An agent can tell immediately what this tool does without opening the schema.

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 clear operational context: it triggers a Touch ID prompt on the user's Mac or a local browser page, the user authenticates on their own device, and the agent must never ask for the passphrase in chat. That covers when/how to use it, though it does not explicitly contrast itself with sibling tools like applock_status or read_hidden.

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