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, the description carries full behavioral burden. It discloses that concealed fields are hidden unless reveal is true, that revealing exposes the secret in the transcript, and that secret references take precedence over IDs. It could add error behavior or permission requirements, but the key security-relevant traits are well covered.

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 core purpose and followed by key behavioral caveats. Every clause adds value (full-item retrieval, hidden fields, input modes, security warning, op_run alternative). No fluff or repetition of obvious 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 read tool with no output schema and no annotations, the description covers purpose, input modes, return contents, and security implications. It is slightly incomplete in not mentioning potential errors or contrasting with item_lookup (likely a lighter variant), but overall sufficient for correct tool selection and invocation.

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 does not add significant meaning beyond the schema; it restates the secret-reference vs. ID relationship already in the parameter descriptions. It adds context about the return contents but not for parameter usage specifically.

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 'Retrieve a full 1Password item' with a specific verb and resource, enumerating contents (title, category, tags, notes, all fields). It also distinguishes from sibling tools by emphasizing the full-item scope and the secret-reference mode, avoiding ambiguity with item_lookup or op_run.

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 gives explicit when-not guidance: revealing a secret puts it in the transcript, and 'to USE a secret in a command or API call, prefer op_run with op:// references instead.' This clearly directs the agent to alternatives for secret consumption while implying this tool is for retrieval.

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 fully owns behavioral disclosure. It states that plaintext secret values are NEVER returned or logged, that every resolved secret is redacted from stdout/stderr, and that injection occurs only in the child process env. These are critical safety behaviors disclosed beyond what the schema provides. No contradiction with 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?

The description is two sentences long, but they are dense and packed with purpose, safety, and usage guidance. Every clause adds value, though the length is slightly above minimal. It remains well-structured and front-loaded with the core action.

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-parameter command runner with no output schema, the description covers purpose, safety, and usage well. It does not explicitly describe the return format or error behavior, but these are not essential for tool selection/invocation. The safety context and usage alternatives make it sufficiently complete.

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 detailed per-parameter descriptions (e.g., env explains the op:// resolution and pass-through behavior). The description adds high-level context about env/redaction but doesn't enrich parameter meanings beyond what the schema already provides, so 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 'Run a local shell command with 1Password secrets injected as environment variables', naming the action and resource, and distinguishes itself from sibling secret-reading tools by explicitly recommending op_run over password_read/item_get for using secrets. This is a specific verb+resource with strong sibling differentiation.

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 says when to use this tool: 'This is the safe way to USE a secret in a command, API call, or script: prefer op_run... over reading a secret with password_read/item_get and pasting it into a command yourself'. It also provides a clear rationale (prevents plaintext in model context/transcript) and names the alternatives, giving complete usage 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 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?

No annotations are provided, so the description carries the full burden. The verb 'List' clearly indicates a non-destructive read operation, and the description adds context about the access scope (service account) and output fields. It does not explicitly mention side effects, but the action inherently implies none.

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 concise sentences with no extraneous text. The action and resource are front-loaded, and the return field list is efficiently provided.

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 simple, parameterless list tool with no output schema. The description fully covers the return values (IDs, names, descriptions, types) and access scope. No further information is necessary for an agent to invoke it correctly.

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 has zero parameters, so baseline 4 applies. The description's phrase 'all vaults' clarifies the default scope, adding modest value beyond the empty schema. No parameter documentation is needed.

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 ('List') with a clear resource ('1Password vaults') and scope ('accessible to the service account'). It also states the return fields (IDs, names, descriptions, types), which distinguishes it from sibling tools that operate on items or passwords.

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 usage context is implied: to list all vaults available to the service account. However, it does not explicitly compare to alternatives or state when to prefer this tool over siblings like item_list or op_check_ref. The resource being vaults suggests usage, but no direct guidance is given.

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