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

Annotations already declare readOnlyHint=false, so the agent knows this is a mutation. The description adds no extra behavioral context—no mention of side effects, permission needs, idempotency, or error behavior. The openWorldHint=true is left unexplained, leaving the agent to guess what additional resources might be created.

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?

A single, front-loaded sentence with no unnecessary words. It states the action and the key requirement immediately, making it easy to scan.

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 mutation with openWorldHint=true and no output schema, the description is too sparse. It does not mention return values, failure modes, duplicate-label behavior, or what 'open world' implies in practice. An agent would have to rely heavily on inference, which is insufficient for reliable 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 75% and the description reiterates that label is required and parent is optional, adding minor clarity. However, hidden and favorite are not addressed in the description, and favorite has no schema description at all. The description adds only 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 states a specific verb and resource ('Create a new folder') and explicitly names the required parameter (label). It is unambiguous and clearly distinct from sibling tools like list_folders, update_folder, and delete_folder, so an agent can easily differentiate it.

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?

No guidance is provided on when to use this tool versus alternatives. The description only touches on parameter requirements (label required, parent optional) and gives no context about prerequisites, exclusions, or relationships with sibling folder tools.

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?

The description discloses server-side encryption and notes that customFields replaces all existing fields (though this is odd for a create, it is a behavioral detail). Annotations already indicate read/write, destructive, and idempotent hints, but the encryption note adds value beyond the metadata.

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, well-structured sentence followed by a brief encryption note. It avoids redundancy and uses parallel lists, making it easy to scan quickly.

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 description covers the essential information: required vs. optional fields, encryption, and custom field constraints. It does not mention return value or error cases, but those are not required given the absence of an output schema. It is sufficiently complete for an agent to invoke the tool 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 schema provides descriptions for several parameters (label, password, folder, hidden, customFields, and customFields.type), and the description text clarifies that username, url, notes, folder id, and favorite are optional. It also gives constraints on customFields (max 20, label/value lengths), compensating for the 56% schema description coverage.

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?

Clearly states the action 'Create' and the resource 'a new password entry'. It also lists required and optional fields, and the name distinguishes it from sibling tools like update_password, delete_password, and list_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 description makes the purpose obvious, but it does not explicitly explain when to choose this tool over alternatives (e.g., use update_password for existing entries). It also lacks guidance on typical scenarios or prerequisites beyond the required fields.

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?

Beyond the destructiveHint annotation, the description discloses that the operation is reversible, affects contents as well as the folder, refuses already-trashed folders, and can never permanently delete. This gives the agent a clear and honest model of side effects.

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-loads the main action and scope, and adds only relevant caveats. No filler or redundant wording is present.

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 one parameter and no output schema, the description is complete: it states the action, the scope including contents, the reversibility, and a key error/refusal condition. An agent has enough context 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 schema already fully covers the single required parameter, and the description repeats the core semantic: 'Id of the folder to trash.' It adds no additional detail such as ID format, validation rules, or source of the ID, so it stays at the baseline for high schema coverage.

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 moves a folder and its contents to the trash, describing the action, resource, and side effects. It is obvious this is the soft-delete operation for folders and is distinct from password operations or folder restoration.

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 explains when the tool applies and its limits: it is a reversible, soft delete and refuses to act on an already-trashed folder. It does not explicitly name alternatives like restore_folder or permanent deletion, but the boundaries are clear enough for an agent to select the correct operation.

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?

Description fully discloses the side effect (soft delete to trash) and explicitly states it can never permanently delete anything. It also mentions the refusal condition for already-trashed entries, going beyond the annotation flags.

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, no redundant information, and the key points are front-loaded. Highly efficient and readable.

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 simple action and no output schema, the description covers all necessary aspects: action, reversibility, edge case, and guarantee of non-permanence. No missing context 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 only parameter 'id' is clearly documented in the schema as 'Id of the password to trash', and the description consistently references it. Full parameter coverage with no ambiguity.

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?

Description clearly states it moves a password to trash as a reversible soft delete, distinguishing it from any permanent deletion. It specifically identifies the action and resource.

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?

Description explains the behavior and edge case (refuses if already trashed), making it clear when to use this tool. It also implies the alternative restore process via the Passwords app, aligning with sibling tools.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds 'Fetch' which aligns with read-only behavior but provides no additional context about error handling or return format. With annotations covering the core, a 3 is appropriate.

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 with zero waste. It states the essential information clearly and nothing else.

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 get-by-id tool with one parameter and annotations covering safety, the description is adequate. It implies the return of a folder object, and no output schema exists to clarify further. The lack of error conditions is a minor gap but acceptable for such a straightforward operation.

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% (the 'id' parameter is described as 'The folder id'). The description repeats this by saying 'by its id', adding no new semantic meaning. Baseline 3 applies when the schema already documents the parameter fully.

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 'Fetch a single folder by its id' uses a specific verb and resource, clearly distinguishing it from list_folders (which returns multiple) and other folder operations. The scope is unambiguous.

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 for when to use this tool: when you have a specific folder id. It does not explicitly mention alternatives or exclusions, but the purpose is self-evident enough that an agent can infer not to use it for listing all folders.

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?

The readOnlyHint annotation already signals no modification, and the description reinforces sensitivity by warning about exposing credentials. While it does not explicitly state 'read-only' in prose, the annotation covers that aspect, and the warning about misuse adds useful behavioral context beyond the annotation.

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 concise, using two sentences to convey purpose, usage constraints, and a pointer to related tools. There is no redundant wording or unnecessary detail.

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 description covers what the tool returns (plaintext secret, notes, custom fields), when to use it (specific id from user), and how to obtain valid ids. Combined with readOnlyHint and openWorldHint annotations, it provides enough context for an agent to invoke it correctly without additional information.

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 single parameter 'id' is clearly described as the password id to reveal, matching the schema description exactly. No further detail is provided (e.g., expected format or source), but the explanation is sufficient for correct usage given the tool's narrow scope.

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: to reveal a single password entry by its id, including plaintext secret, notes, and custom fields. It also distinguishes itself from list_passwords and search_passwords by explicitly noting that ids come from those tools.

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 explicit usage guidance: only call it for a specific id the user has asked to see, and never for bulk export. It also directs callers to obtain ids via list_passwords or search_passwords, reducing ambiguity about when to use this tool.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds the valuable note that 'Folders hold no secret material,' which sets expectations about content sensitivity, and it specifies the returned fields. It doesn't describe pagination or ordering, but for a read-only list tool this is adequate given the annotation coverage.

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, no wasted words. The first sentence front-loads the core purpose and return fields; the second provides a practical usage pointer. 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?

For a parameterless tool with annotations covering safety and open-world behavior, and no output schema, the description is complete. It tells the agent what it returns, that it's safe (no secrets), and how to chain it with a sibling tool. Nothing an agent needs to call it correctly is missing.

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?

With zero parameters and 100% schema coverage (empty properties), there is nothing to document. The description adds value by explaining how the output (folder ids) can be used with list_passwords, which is a semantic clarification beyond the schema. Baseline for 0 params is 4, and the description meets it.

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 (List), resource (folders), and enumerates the returned fields (id, label, parent folder id, timestamps). It clearly distinguishes itself from sibling tools like list_passwords (which lists passwords) and get_folder (which retrieves a single folder) by indicating scope as 'all folders'. No ambiguity.

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 provides a direct cross-tool usage hint: 'Use a folder id with list_passwords to filter.' This tells the agent how to apply the output. It doesn't explicitly state when not to use this tool or compare with get_folder, but the purpose is clear enough that an agent can infer the appropriate context.

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?

Annotations already declare readOnlyHint=true, so the description adds value by stating the secret value is never included and that only metadata fields are returned. This is beyond the annotation and clarifies the tool's non-destructive, metadata-only nature. No contradiction.

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: the first states the main purpose and scope, the second adds the critical caveat about secret exclusion and the optional filter. Every sentence carries meaningful information, with the most important detail (metadata only) front-loaded.

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-only list tool with one optional parameter and no output schema, the description covers the return fields, the exclusion of secrets, the pointer to get_password for secret retrieval, and the optional filter. An agent has enough information to decide when to use this tool and how to call 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 single parameter 'folder' is fully described in the schema as 'Optional folder id to filter by.' The tool description repeats the same optional filtering concept without adding syntax or format details. Since schema coverage is 100%, the description adds no extra parameter semantics beyond a restatement.

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 (list), resource (saved passwords), and clarifies the metadata-only scope, naming the exact fields returned. It also distinguishes itself from get_password by explicitly stating the secret is never included. This clearly separates it from sibling tools like search_passwords and get_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?

It explicitly says to use get_password with a specific id to reveal a secret, giving clear direction on when to switch to an alternative. It also mentions optional folder filtering, but does not explicitly discuss when to prefer search_passwords over list_passwords. The context is clear for the core use case.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces 'Reads no vault data.' It adds specific checks (URL, app-password, app installed, encryption disabled) beyond annotations, providing valuable context for an agent deciding whether to call it. No side effects are implied.

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 with no wasted words. The primary purpose is front-loaded, followed by the specific checks and the read-only guarantee. Every clause 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?

For a zero-parameter diagnostic tool with readOnlyHint and openWorldHint annotations, the description fully covers what the tool does and what it does not do. No output schema exists, but for a connectivity check, the agent has everything needed 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 schema coverage is 100% by default. The description adds nothing about parameters because none exist, and there's nothing to clarify. Baseline 4 is appropriate for a no-parameter tool.

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 ('Verify connectivity') and resource (Nextcloud Passwords instance), enumerates exactly what is checked (URL, app-password, app installation, client-side encryption), and clarifies it reads no vault data. This clearly distinguishes it from all sibling data-operation tools like list_passwords or get_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 implicitly signals this is a diagnostic/health-check tool to be used when verifying setup, and explicitly notes it reads no vault data, implying it's safe to call anytime. It does not explicitly name alternatives or conditions, but the purpose is self-evident and no exclusion is needed.

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?

Beyond annotations, the description reveals that the tool only removes the folder from trash and never rolls it back to an older revision, and that it errors if the folder is not in the trash. This adds meaningful behavioral context that the annotations do not provide, such as the non-revision behavior and error condition.

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 primary purpose and then a concise clarification of limitations and error behavior. Every sentence adds value, with no wasted 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?

For a single-parameter, simple operation, the description fully covers what the tool does, what it does not do, and its error condition. Since there is no output schema, no return value details are expected, and the description is complete for correct 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?

The schema already provides full coverage (100%) with a clear description for the 'id' parameter ('Id of the trashed folder'). The tool description does not add extra detail about the parameter, 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 clearly states the tool's action with a specific verb ('Restore') and resource ('trashed folder'), and directly ties it to 'undoing delete_folder'. This distinguishes it from sibling tools like restore_password, which operate on a different resource type.

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 when to use it via 'undoing delete_folder' and provides a condition: it reports an error if the folder is not in the trash, so it should be used only for trashed folders. However, it does not explicitly contrast with alternatives like restore_password, though the resource type makes that implicit.

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?

The annotations indicate readOnlyHint=false and destructiveHint=false, aligning with the description's statement that it modifies state (restores from trash) without being destructive. The description adds valuable detail about not rolling back to older revisions and reporting an error when the item is not in the trash, which goes beyond the 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, directly stating the action, its scope, and error behavior. No redundant words or tangential information, making it highly concise and 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?

For a simple tool with one input and no output schema, the description covers the purpose, the exact effect (removes from trash only), what it doesn't do (revision rollback), and the error case. This is sufficient for an agent to invoke it correctly without further context.

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 only parameter 'id' is described in the schema as 'Id of the trashed password.' The description repeats this without adding new meaning (e.g., format, constraints, or examples). Since schema coverage is 100%, the baseline of 3 applies.

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?

Clearly states it restores a trashed password and explicitly ties it to undoing delete_password. The description also distinguishes it from a revision rollback, which prevents confusion with other operations.

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 direct guidance on what the tool does and does not do (only removes from trash, never rolls back to older revision). It also mentions the error condition when the password is not in the trash, which helps set expectations. However, it does not explicitly contrast with restore_folder, though the sibling list makes the distinction inferable.

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?

Beyond the readOnlyHint annotation, the description adds critical behavioral details: case-insensitive matching, metadata-only returns, and no secret values exposed. This fully sets expectations for the tool's 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 two concise sentences, front-loading the action, then clarifying the output scope and follow-up step. No unnecessary words or 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?

For a simple search tool, the description provides all necessary context: what it searches, how it matches, what it returns, and how to proceed to obtain the actual secret. The sibling tool landscape makes the purpose and usage unambiguous.

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 single 'query' parameter is described as a substring to match on label/username/url, which aligns with the tool's purpose. The tool description adds case-insensitivity, making the parameter's meaning fully clear.

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 searches saved passwords by case-insensitive substring across label, username, or URL, and explicitly notes it returns metadata only. This distinguishes it from siblings like list_passwords (which likely lists all) and get_password (which retrieves a specific secret).

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 instructs to use get_password with an id from results to reveal a secret, providing a clear next step. The case-insensitive substring behavior and metadata-only return give concrete guidance on when to invoke this tool versus 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?

The description discloses the side effect that hiding a folder hides its contents. The annotation destructiveHint=true is consistent with that side effect, though other potential side effects (e.g., moving affecting child paths) are not mentioned.

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: first lists the actions, second explains partial update and the hiding side effect. No unnecessary detail.

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 description is sufficient to distinguish from sibling tools and provides the key behaviors needed to call it. It does not mention the return value or error conditions, but that's minor given the absence of an output schema.

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 descriptions cover id, hidden, and parent, but label and favorite lack descriptions. The tool description provides some context for these (rename, favorite state), but the semantics are not fully detailed.

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 that the tool renames, moves, toggles favorite/hidden state, and specifies that it operates by id. This distinguishes it from create/delete/restore folders.

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 explains partial update behavior (fields not passed keep current value) and notes the side effect of hiding contents. While it doesn't explicitly mention alternatives, the sibling tools are distinct enough that an agent would know when to use this for modifications.

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?

The description discloses important side effects beyond annotations, including that customFields is fully replaced, hidden/favorite state is preserved, tags are untouched and uneditable, and the server rejects writes if the entry changed underneath. This is transparent about destructive behavior and complements destructiveHint: true.

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 concise and front-loaded, stating the purpose first and then adding necessary caveats in a compact manner. No unnecessary words or redundant restatements appear.

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 output schema, the description provides the key operational context: partial update behavior, customFields replacement, tags limitation, required field constraint, and optimistic concurrency rejection. This is sufficient for an agent to use the tool effectively.

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 only 30%, and while the prose clarifies update semantics and customFields behavior, several individual parameters like url, label, notes, folder, password, username, and favorite lack explicit format or meaning. In particular, folder is ambiguous (ID vs name) and no validation details are given for most fields.

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 updates fields of an existing password by id, using a specific verb and resource. This distinguishes it from sibling tools like create_password, delete_password, restore_password, and search/get variants.

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 usage guidance: only passed fields are changed, other fields are preserved, customFields replaces the entire set, tags cannot be edited, and at least one field besides id must be provided. It also notes concurrency rejection, which helps the agent decide when and how to invoke the tool safely.

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