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

No annotations are provided, so the description carries the full burden. It discloses that the item is 'moved to the archive and hidden from regular views,' and clarifies the non-destructive nature by contrasting with permanent deletion. This is meaningful behavioral context beyond a simple verb, though it could mention reversibility or permissions.

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?

Two sentences, front-loaded with the primary action, and every word earns its place. The distinction from deletion is packed efficiently into the second sentence without redundancy.

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?

The tool is simple with two well-documented required parameters and no output schema. The description covers the core behavior and its non-destructive nature, making it contextually complete for typical use. A minor gap is lack of mention of how archived items are accessed or restored, but that is not essential.

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 100%, with both 'vaultId' and 'itemId' already documented. The description adds no additional parameter context, so it does not exceed the baseline of 3.

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 action ('Archive') and the resource ('an item in a 1Password vault'), and distinguishes the tool from sibling item_delete by explicitly noting it is 'rather than being permanently deleted.' This is a specific, differentiating purpose statement.

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?

The description implies usage context by contrasting archiving with permanent deletion, helping the agent choose between item_archive and item_delete. It does not explicitly name sibling tools or provide when-not-to-use guidance, but the 'rather than being permanently deleted' phrase gives clear contextual direction.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly warns that deletion is permanent and irreversible, which is the most critical behavior for a delete tool. It does not cover permissions or return values, but the core risk is clearly communicated.

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 two concise sentences with no filler. 'Permanently delete an item from a 1Password vault' is front-loaded and immediately actionable, followed by the critical warning. Every word earns its place.

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?

The tool is simple (two required string parameters) and the description fully conveys the action and its permanence. It does not mention return values, but for a delete operation this is less critical. Given no output schema and no annotations, the description sufficiently covers the context, though it could add 'on success' or error behavior.

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?

The schema already provides full descriptions for both parameters (itemId and vaultId), and schema coverage is 100%. The tool description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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: 'permanently delete an item from a 1Password vault'. It clearly distinguishes from siblings like item_archive by emphasizing permanence, and from item_edit by focusing on deletion.

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?

The description makes it clear that this tool is for irreversible removal ('This action cannot be undone'), which implies when to use it. However, it does not explicitly mention alternatives (e.g., item_archive for reversible deletion) or when not to use it. The context is clear but lacks explicit exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the critical partial-update behavior ('Only referenced fields are changed; all others are preserved') and the destructive edge case for clearing notes. This goes well beyond a simple 'update' statement, though it omits potential error conditions.

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?

Two sentences, essentially zero waste. The main action is front-loaded, followed by specific details (empty string clears notes, only referenced fields change). Highly efficient and scannable.

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 moderate-complexity edit tool, the description covers all update operations and key behavior. With complete parameter schemas, it need not repeat return details. Minor omissions like item-not-found error handling are not significant enough to lower further.

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%, so the baseline is 3. The description adds important cross-cutting semantics beyond individual parameter docs: the overall partial-update contract and the upsert/remove behavior for fields. This enriches understanding of how parameters interact.

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 opens with a specific verb+resource ('Edit an existing 1Password item') and lists all supported update operations (title, notes, tags, URL, fields, remove fields). This clearly distinguishes it from sibling tools like item_delete or item_archive by focusing on modification.

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?

The description implies usage for editing existing items but does not explicitly state when to prefer this over alternatives. It gives no direct comparison to password_update or item_delete, though the edit-focused verbs make context clear. This is acceptable but not explicit.

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

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 so well: it discloses that secret-bearing values (passwords, SSH keys, OTP seeds, card numbers) are hidden by default, lists the non-secret types that are shown, and warns that revealing places the secret in the model context/transcript. It omits auth/permission requirements and any rate-limit behavior, which keeps it short of a 5.

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?

Content is front-loaded — what is retrieved first, then the reveal semantics, then the op_run alternative. It is dense but every sentence earns its place; the only mild cost is that the second sentence packs several lists into one long 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 read tool with no output schema and no annotations, the description covers the key things an agent needs: what is returned, what is redacted by default, how to select the item, and the safer alternative for using secrets. Remaining gaps (auth prerequisites, error modes) are minor given there is no output schema to lean 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?

Although schema description coverage is 100% (baseline 3), the description adds real meaning beyond the schema: the op://vault/item/field reference format, the precedence rule that secretReference causes vaultId/itemId to be ignored, and the hidden-vs-visible type taxonomy tied to reveal. That extra semantic layer justifies a bump above 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?

The description states a specific verb ('Retrieve') and resource ('a full 1Password item') and enumerates the returned surface (title, category, tags, notes, all fields), which implicitly separates it from lighter siblings like item_lookup or item_list. An agent can tell what shape of result it gets 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?

It gives clear routing guidance for the secret-handling case: 'to USE a secret in a command or API call, prefer op_run with op:// references instead,' which is an explicit alternative and a when-not for reveal=true. It does not, however, clarify when to choose item_get over item_lookup or item_list, so the coverage is strong but not exhaustive.

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

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

No annotations are provided, so the description carries the burden. It adds a meaningful behavioral guarantee with 'Never returns secret values' and specifies the return fields, providing useful transparency for a read-only operation. It does not mention permissions or pagination, but these are less critical for a simple listing tool.

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 two concise sentences with no filler. Each sentence earns its place: the first covers scope and return fields, the second adds a critical safety guarantee.

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 simple listing tool, the description adequately covers purpose, return shape, and a safety constraint. It lacks explicit usage alternatives and a clear read-only label, but the core information needed for correct invocation is present.

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 100% for vaultId, so the baseline of 3 applies. The description does not add any parameter-specific meaning beyond the schema; it only repeats the concept of a vault without clarifying ID format or source.

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 tool lists all items in a 1Password vault and enumerates the returned fields (id, title, category, tags, updatedAt). This distinguishes it from sibling tools like item_lookup or item_get, which focus on individual items.

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?

The phrase 'List all items' implies a bulk retrieval use case, but there is no explicit guidance on when to use this tool versus alternatives such as item_lookup or item_get. No exclusions or alternative references are provided.

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

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

Without annotations, the description carries the full burden. It discloses the return fields (IDs, titles, categories, vault IDs) and the substring matching behavior, which is useful. However, it does not explicitly state that it is a read-only operation, nor does it mention any pagination or default behavior when query is omitted—though the schema covers limit.

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 two concise sentences, front-loaded with the primary action and resource. There is no redundant or filler content; every word contributes to understanding the tool's purpose and output.

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 simple search tool with fully documented parameters and no schema, the description provides key information: purpose, matching method, and returned fields. However, it does not explain behavior when query is omitted (which the schema implies returns all items) or any result ordering, leaving a small gap in completeness.

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 100%, so the baseline is 3. The description adds minimal semantic value beyond the schema: it reinforces that the query is a title substring filter and that the search is vault-scoped, but these are already in the schema descriptions.

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 action ('Search for items') with a precise resource ('1Password vault') and method ('by title substring'). It clearly distinguishes from siblings like item_list (which likely lists all items) and item_get (single item retrieval) by specifying substring search.

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?

The description implies usage for finding items by title substring but does not explicitly state when to prefer this over item_list or other alternatives, nor does it give exclusions. It gives minimal context but lacks explicit 'use when' or 'instead of' guidance.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It identifies the action as 'create' but does not mention authentication requirements, whether existing items are affected, or what happens on success or failure.

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 one short sentence that immediately states the primary action and includes relevant optional features. It avoids unnecessary words and is well structured.

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?

The tool is a create operation with no output schema and no annotations, yet the description does not explain return values or error scenarios. However, the schema thoroughly covers parameters, so the description is moderately complete but not fully self-sufficient.

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?

The input schema provides full descriptions for all 5 parameters, including notes, tags, fields, title, and vaultId. The description adds only a brief mention of optional tags and custom fields, which adds no new semantics beyond the schema.

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 tool creates a Secure Note item in a 1Password vault, using a specific verb and resource, and mentions optional tags and custom fields. It distinguishes itself from sibling password_create by focusing on notes.

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?

The description does not explicitly state when to prefer this tool over alternatives like password_create, nor does it mention exclusions. The tool name and note-specific context imply its intended use, but no explicit guidance is provided.

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

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

With no annotations provided, the description fully carries the safety disclosure. It explicitly states that the field VALUE is never returned and lists the non-secret metadata returned (vault name, item title, field label, field type), which is essential for trust and safe use.

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 two sentences, front-loaded with the action and safety guarantee, and contains no fluff. Every phrase adds value, making it both concise and effective.

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 validation tool with no output schema, the description covers all necessary context: the input format, the validation purpose, the non-sensitive return data, and the usage scenario. It is fully self-sufficient even without annotations.

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?

The schema description already fully documents the parameter ('Secret reference to validate, in op://vault/item/field format.'), covering 100% of the parameter's meaning. The description adds no extra parameter semantics, so the baseline score of 3 is appropriate.

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 tool's purpose with the verb 'validate' and the resource 'op://vault/item/field secret reference'. It also distinguishes itself from sibling tools like password_read and item_get by explicitly saying not to use those for the same 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?

It explicitly directs when to use the tool ('Use this to check a reference is correct before using it with op_run') and when not to ('do not use password_read/item_get with reveal just to check a reference exists'). This is excellent, unambiguous guidance.

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

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

With no annotations, the description carries the full burden and does so well: it specifies that resolved values live only in the child process environment, are never logged by the server, and are redacted from stdout/stderr on a best-effort basis across JSON/URL/base64 encodings — and candidly admits the limit that a command which transforms or transmits a secret can still leak it. It stops short of characterizing the side-effect/risk profile of executing arbitrary shell commands (filesystem, network, privilege), which matters for a tool with no annotations.

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?

Front-loaded with the action and its differentiator, then the security caveat, then the routing preference — no sentence is filler. The encoding list and the long final clause are dense but each carries actionable information, so the length is justified for a security-sensitive tool.

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?

Covers purpose, secret-handling behavior and sibling routing for a 7-parameter tool with nested objects. The gap is the return contract: there is no output schema, and the description never states what the caller gets back (stdout/stderr/exit code shape), which an agent needs to interpret results.

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 100%, so the schema already documents cwd, env, argv, shell, stdin, command and timeout_ms, including the command-vs-argv exclusivity. The description's discussion of `env` and op:// resolution restates what the schema says rather than adding format or edge-case detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Combines a specific verb and resource ('Run a local shell command') with the distinguishing capability ('1Password secrets injected as environment variables'), which no sibling tool offers. It also explicitly names the sibling behaviors it supersedes (password_read/item_get), so an agent can route without opening any 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?

States the preferred path and the exact alternative it replaces: use op_run with op://vault/item/field references in `env` rather than reading a secret and pasting plaintext into a command. The condition for choosing it is explicit, not inferred.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions it's a create operation but does not address permissions, reversibility, response format, or security implications such as the returnSecret behavior.

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 a single, front-loaded sentence that efficiently conveys the core purpose without extra words.

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 9 parameters, no annotations, and 13 sibling tools, the description is somewhat sparse. It names the resource and optional fields but lacks usage differentiation and return value expectations; however, the schema covers parameter details, making it minimally viable.

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%, so the schema fully documents all 9 parameters. The description adds only a summary of optional fields (username, URL, tags, notes), which adds marginal value beyond the schema.

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 tool creates a new password/login item in a 1Password vault, with a specific verb and resource. It distinguishes from siblings like password_update (update) and password_generate (generate a password).

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?

The description provides no guidance on when to use this tool versus password_update, password_generate, or note_create. It simply states the action without exclusions or alternatives.

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

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

With no annotations, the description carries the full burden. It adds valuable behavioral details: 'cryptographically secure' and 'unbiased randomness' via rejection sampling. However, it does not disclose potential return format, non-storage guarantees, or any error conditions. It provides some behavioral context but not a rich profile.

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?

Two sentences, both purposeful: the first states the core function, the second provides a meaningful algorithmic detail. No wasted wording, and key information is front-loaded. This is an excellent example of concise, well-structured description.

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 simple tool with all parameters documented and defaults in the schema, the description covers security and randomness quality. It lacks any comparison to sibling tools or guidance on when to use it, but the core functionality is fully explained. The output (a password) is implied, and there is no output schema to elaborate. Slightly incomplete due to missing alternative guidance.

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%, so the schema already fully documents all parameters with descriptions and defaults. The description only summarizes 'configurable length and character types', adding no additional meaning beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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 it generates a password with configurable length and character types, specifying it is cryptographically secure. It does not explicitly differentiate from the sibling tool password_generate_memorable, but the 'cryptographically secure' phrasing implies the intended use case. This is clear but lacks explicit sibling comparison.

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?

There is no guidance on when to use this tool versus alternatives such as password_generate_memorable, nor any mention of prerequisites or typical use cases. The description does not state exclusions or recommend this tool for specific scenarios, leaving the agent without direction for tool selection.

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

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

With no annotations, the description carries the transparency burden. It discloses the word list size (~500 words), the use of optional number/symbol suffixes, and the random dictionary word approach, which provides useful behavioral context beyond the bare function.

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 two sentences, front-loaded with the core function, and every sentence adds value. No filler or redundant repetition of schema details.

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 no annotations or output schema, the description covers the core generation behavior and entropy context. However, it lacks usage differentiation from sibling password_generate, which is a notable gap for a tool in a list with overlapping functionality.

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 100%, so parameters are already well-documented. The description adds minimal extra parameter semantics; it only mentions 'optional number and symbol suffixes' which aligns with the schema. Baseline 3 is appropriate.

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 tool's function: generating a memorable passphrase from random dictionary words. It also distinguishes it from likely siblings like password_generate by emphasizing 'memorable' and the use of a curated word list.

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?

The description implies the use case (memorable passphrases) but does not explicitly contrast it with alternatives like password_generate. No when-to-use or when-not-to-use guidance is provided.

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

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

With no annotations, the description carries the full burden. It discloses that reveal puts the secret in the transcript, defaults to metadata-only, and clearly states the read-only nature of retrieval. The transcript warning is critical and well-addressed, though other behavioral details like permissions are absent.

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 focused sentences with the main purpose first, followed by critical usage caveats. No redundant words, perfectly front-loaded, and each sentence earns its place.

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?

Given the tool's moderate complexity, no annotations, and no output schema, the description covers the key aspects: input modes, field selection, reveal behavior, and an alternative tool. It could mention return format in more detail, but the metadata-only vs revealed distinction suffices for an agent to understand what to expect.

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%, but the description adds value by explaining the two lookup modes (secretReference vs vaultId+itemId) and the default metadata-only behavior, which clarifies parameter relationships beyond individual schema descriptions.

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 tool retrieves a secret from 1Password, specifying two input modes (secret reference or vault ID + item ID). It distinguishes from siblings by explicitly directing users to op_run for using secrets in commands/API calls.

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?

Provides explicit guidance to prefer op_run with op:// references when the secret is to be used in a command or API call, and warns against unnecessary reveal. It doesn't mention item_get as an alternative for non-secret retrieval, but the main ambiguity with op_run is resolved.

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

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

Without annotations, the description carries the full burden. It discloses one behavioral trait: if the target field does not exist, it will be created. However, it does not mention permissions, reversibility, side effects, or what happens to the item's metadata, which are important for a mutation tool.

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 two sentences, with the main action stated first and the key side-effect in the second sentence. Every word contributes value; there is no fluff or repetition.

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?

This is a mutation tool with no output schema and no annotations. The description covers the core action and creation behavior, but it does not explain return values or clarify when to choose this over sibling item_edit, which could also modify fields. Given the low complexity, a 3 is appropriate.

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 100%, so the baseline is 3. The description adds no extra parameter semantics beyond what the schema already provides, but since the schema is thorough, the description does not need to compensate.

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 uses a specific verb 'Update (rotate)' and clearly identifies the resource: a password or concealed field on an existing 1Password item. This distinguishes it from sibling tools like password_create (which creates new items) and password_read (which reads values).

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?

The description provides clear context by stating it applies to 'an existing 1Password item,' implying it is not for creation. However, it does not explicitly mention alternatives or when-not-to-use scenarios, so it falls slightly short of a 5.

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

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

With no annotations, the description carries the full burden and does disclose a real behavioral constraint: results shrink to the allow-listed vaults when OP_MCP_ALLOWED_VAULTS / --allowed-vaults is configured. It also specifies returned fields. It stops short of stating read-only nature, auth requirements, or pagination/rate limits.

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?

Two compact sentences, front-loaded with the core action and followed by the scoping caveat and return fields. No filler or repetition.

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 parameterless read tool this is nearly complete: scope, filtering behavior, and return shape are all covered, which compensates for the absent output schema. Only auth/permission expectations and result-size behavior are unstated.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of returned fields is return-value information rather than parameter semantics.

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 ("List the 1Password vaults") and scopes it precisely to those accessible to the service account. An agent can immediately distinguish this vault-enumeration tool from the many item_* siblings that operate on items within vaults.

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?

The allow-list caveat implies the tool is the discovery entry point, but there is no explicit when-to-use guidance, no mention of prerequisites (e.g., required credentials), and no routing to alternatives such as item_list for enumerating contents. Usage must be inferred.

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