keymaster-mcp

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

Annotations already declare this is a non-destructive write operation (readOnlyHint false, destructiveHint false), and the description adds valuable behavioral detail about secret handling, such as clipboard clearing, secure macOS prompt, and generated secrets. It does not state prerequisites like whether the vault must be unlocked, which leaves a behavioral gap.

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-loads the core purpose and lookup keys before detailing secret_source. The bullet-style list for secret_source is structured and readable, though the description unevenly spends space on some parameters while omitting others.

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 an 18-parameter credential-creation tool with no schema descriptions and no output schema, the description is incomplete. It covers several key fields well but leaves many parameters and the vault/auth state unaddressed, which is a significant gap for a highly parameterized tool.

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 schema description coverage at 0%, the description must compensate, and it does explain name, aliases, urls, tags, secret_source, secret_field, extra_secrets, fields, and policy. However, it leaves many parameters undocumented, including type enum values, notes, username, expires_at, rotate_days, generate_kind, and generate_length.

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?

Starts with a specific verb and resource: 'Store a new credential.' The word 'new' distinguishes this from update_credential and other sibling mutation tools, so an agent can identify its role 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?

Offers no explicit guidance on when to choose add_credential over siblings or when not to use it. The only preference note—'prefer ones that keep it out of the chat'—concerns the secret_source parameter, not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the content of the log (actor/action/timestamp), but says nothing about ordering, pagination, or what 'recent' means in practice.

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?

One short parenthetical sentence, front-loaded with the resource and immediately followed by the optional filter. No filler.

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 read-only tool with no output schema and zero required parameters, the description is adequate but leaves the two parameters (ref format, limit semantics) and the log's ordering/unbounded-history behavior unaddressed.

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 0%, so the description carries the burden. It clarifies that 'ref' is optional and scopes the log to a single credential, but never defines the accepted ref format (id vs name) and ignores 'limit' and its default of 30 entirely.

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?

Names a specific resource and scope: recent vault activity with the categories of events (revealed/used/changed) and the temporal frame (when). An agent can tell this is an activity feed, distinct from credential_history or list_credentials, though the relation to credential_history is not spelled out.

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 'Optionally for one credential' implies the unfiltered-by-default behavior and the filter case, but it never states when to prefer this over credential_history or how far back 'recent' reaches.

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 only give readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds the traits that actually matter here: default field behavior, auto-clear after N seconds, and the security property that the agent never observes the value. It doesn't say whether the clipboard write is reversible/overwrites prior contents or what happens if the copy fails, which keeps it from 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?

Three compact sentences, front-loaded with the core action, then the clearing behavior, then the security guarantee. No filler and nothing repeated from the schema.

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 4-parameter tool at 0% schema coverage with no output schema, the description covers the security behavior well but leaves real gaps: the unexplained 'purpose' parameter and the ambiguous role of the required 'ref' versus the 'default: main secret' claim. Adequate to invoke in the common case, incomplete for anything off the default path.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry all four parameters. It explains the default field and gives example field values, and roughly covers 'seconds' ('auto-clears after N seconds'), but says nothing about the 'purpose' parameter and never clarifies what 'ref' is (credential id, name, or alias) or why it is required despite the phrase 'default: main secret'.

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 concrete verb+resource+destination ('Copy a secret ... to the macOS clipboard') and immediately clarifies scope with the field options ('main secret', 'username', 'totp', any field). The clause 'the agent never sees it' sharply distinguishes it from value-returning siblings like get_credential.

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?

'For the human to paste' plus 'the agent never sees it' tells the agent exactly the situation this tool exists for: when the secret must reach the user's clipboard without entering model context. It does not explicitly name the alternative (get_credential) or say when NOT to use it, so it stops 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: secret values are hidden, i.e. the agent should not expect retrievable plaintext. It does not describe ordering or volume of returned versions.

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?

One sentence, front-loaded with the resource and scope, with the parenthetical caveat placed immediately after the noun it qualifies. Nothing is wasted.

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 read-only lookup with no output schema, the description covers what is returned (previous versions, redacted values) and why it exists. The main gap is the opaque 'ref' parameter, but the retrieval semantics and safety posture are otherwise adequately conveyed.

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?

There is one parameter, 'ref', with 0% schema description coverage, so the description must carry the semantic burden. It only implies that ref points at a credential via the phrase "a credential's secrets" and gives no format, identifier type, or example, leaving the single required parameter effectively undocumented.

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 names a specific resource (a credential's secrets) and specifies that it returns previous versions, which clearly separates it from get_credential (current values). It does not explicitly name or contrast with siblings like rollback_credential or audit_log, so it stays just short of 5.

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?

"for auditing / rollback" implies the workflow contexts in which this tool is used, giving more than nothing. But it never says when to prefer this over get_credential, rollback_credential, or audit_log, so the guidance remains implied rather than 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?

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that it returns the 'main secret field' of each type, but says nothing about the return shape or ordering. With annotations carrying the safety burden, this is adequate but not rich.

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 short sentence with no filler, and the core content (types + secret field) is front-loaded. It is efficient, though the missing verb slightly weakens the lead.

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 no output schema and zero parameters, the description carries the full burden of describing the return value. It does state what comes back (supported types and their main secret field) but not the format or how the 'main secret field' is represented, leaving a gap for an agent deciding how to consume the result.

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 per the rubric the baseline is 4; there is no parameter semantics for the description to clarify or omit.

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 is a noun phrase ('The supported credential types and the main secret field of each') rather than a verb+resource statement, so it never says explicitly that it returns/lists anything. The resource is nonetheless identifiable, and it is distinguishable from credential-manipulation siblings like list_credentials or get_credential, but the lack of a verb leaves purpose slightly vague.

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 about when to call this versus list_credentials, get_credential, or find_credentials, and no mention of prerequisites or typical workflow. The agent must infer usage purely from the name.

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 already state destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds important context beyond the annotations: the operation is reversible via restore_credential, meaning it is a soft delete rather than a permanent one. It does not cover permission requirements or return behavior, but for a simple mutation with annotation coverage, this is a substantial addition.

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 wasted words. It states the action, the result, and the recovery path in one efficient clause. Every part 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 simple one-parameter mutation tool, the annotations cover the safety profile and the description adds the crucial soft-delete nuance. However, the parameter 'ref' is entirely undocumented in both the schema and the description, which leaves a significant gap for correct invocation. The description is adequate but not complete enough to guide an agent on what value to pass.

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 0% for the single required parameter 'ref,' and the description does not explain what 'ref' should contain (e.g., an ID, name, or UUID). The phrase 'a credential' implies that ref identifies a credential, giving minimal semantics, but no format or example is provided. The description fails to compensate for the total lack of schema documentation.

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 and resource: 'Move a credential to the trash.' It also clarifies the operation is a soft delete by noting it is 'recoverable with restore_credential,' which distinguishes this tool from the sibling purge_credential (permanent deletion). An agent can immediately understand the scope and consequence 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?

The description contains no explicit guidance on when to use this tool versus alternatives such as purge_credential, update_credential, or revoke_approvals. The mention of restore_credential only describes the recovery path, not the conditions that should select this tool. An agent is left to infer that 'move to trash' means a reversible delete, but no alternatives or exclusions are stated.

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 only cover the safety profile (readOnly, non-destructive, closed-world), but the description adds return semantics an agent genuinely needs: ranked matches, metadata-only with secrets hidden, and an `ambiguous` flag that signals it should ask the user to disambiguate. That is real behavioral context beyond the structured fields.

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 tight sentences, front-loaded with the applicability rule, then input guidance, then return behavior. No filler; every clause carries information an agent would otherwise have to guess.

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?

No output schema exists, and the description compensates by describing returns (ranked matches, metadata-only, ambiguity flag). It also handles the fuzzy-query contract well. The remaining gap is the undocumented optional filters (tag, type, limit), which an agent may not know it can use.

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 0%, so the description must carry parameter meaning. It does this well for `query` ('pass whatever you have' plus URL/hostname/name/alias/phrase examples), but says nothing about `tag`, `type`, or `limit`, leaving three of four params undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('find credentials') and immediately scopes it as a ranked lookup rather than a list or fetch. The framing 'ALWAYS THE FIRST STEP when anything needs credentials' cleanly distinguishes it from siblings like list_credentials and get_credential, which are enumeration/retrieval 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?

Gives concrete trigger scenarios (login, API call, CLI/DB auth, 2FA, user asking for a password/token/key) and instructs on input flexibility. It stops short of naming the alternatives (list_credentials, get_credential) or stating when NOT to use it, so the routing 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?

The description states that with store_in the generated secret is written into a credential, replacing the old value ('old value kept in history'). That is a state mutation, which directly conflicts with readOnlyHint=true and destructiveHint=false. The added detail about history retention and 'NOT returned' is useful, but it is delivered in contradiction to the structured safety hints.

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 tight sentences, no filler, with the important side-effect warning front-loaded after the core purpose. Slightly telegraphic ('it is written straight into that credential') but efficient.

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 tool with zero schema coverage and no output schema, the description should cover the generation knobs (length/words/symbols) and what happens when store_in is null. It omits nearly all of them and only partially describes the return 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?

Schema description coverage is 0% across 7 parameters, so the description must compensate, yet it only explains store_in (and implicitly kind). words, length, symbols, reason and store_field are left completely undocumented in both the schema and the description.

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 ('Generate a strong password or diceware-style passphrase') and covers both modes via the kind enum. It is clearly distinguishable from the credential-CRUD siblings, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use for the store_in path ('use this for rotation so the new secret never enters the chat'), which is genuinely actionable guidance. It does not say when *not* to use store_in, nor position itself against add_credential/update_credential, so it stops short of full alternative routing.

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 establish readOnlyHint=true and destructiveHint=false, but the description adds behavior annotations cannot express: reveal=true returns raw secret values, is gated by the credential's policy, and 'may pop an approval dialog for the user.' That approval/consent side-effect is exactly the kind of context an agent needs before exposing a secret.

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 sentences, front-loaded with the core action, then the risky reveal path, then the preferred alternative. No filler or restatement of the name.

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 4-param read tool with no output schema and no param descriptions, the description covers the risky path (reveal), the routing alternative, and the purpose requirement. It omits what a non-reveal response contains and what `fields` filters, which are the only real gaps.

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 0%, so the description carries the burden and largely does: it explains the accepted forms for `ref`, the meaning of reveal=true, and the requirement to supply `purpose` when revealing. Only `fields` is left semantically unexplained.

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 ('Get one credential') and enumerates the accepted lookup keys (id, name, alias, URL). The word 'one' implicitly separates it from list_credentials/find_credentials, but no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real routing guidance: 'Prefer http_request/run_with_credential over revealing.' It also conditions reveal on policy and mandates a purpose string. It does not address when to use this vs find_credentials/list_credentials, so it stops short of full coverage.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the result includes the 'seconds remaining', a behavioral detail beyond the annotations, but says nothing about time-sensitivity, caching, or failure when no totp_secret exists.

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 compact sentence with the key precondition and return cue front-loaded. Efficient, though the telegraphic phrasing sacrifices some clarity.

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?

There is no output schema, so the description should carry more, and it never explains the parameters or the failure behavior for credentials lacking a totp_secret. For a low-complexity read tool the annotations cover safety, but the 0% parameter coverage leaves real gaps.

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 0% and neither parameter is explained. The required 'ref' is never defined (identifier? name? UUID?) and the optional 'purpose' parameter with default '' is entirely unaddressed, so the description fails to compensate for the documentation gap.

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+resource ('Current 2FA/TOTP code') and a scoping precondition ('for a credential that has a totp_secret'), which distinguishes it from get_credential and generate_secret. It stops short of explicitly naming siblings, but the purpose 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 'credential that has a totp_secret' clause implies when the tool is applicable, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as get_credential or generate_secret. Usage must be inferred from the precondition.

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?

Adds genuinely useful behavioral detail beyond the annotations: the optional breached check, the HaveIBeenPwned k-anonymity mechanism, and that only 5 hash chars leave the machine. However, this external call to HaveIBeenPwned conflicts with the openWorldHint=false annotation, which claims no external-world interaction, creating an inconsistency.

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 tight sentences that front-load the verb and scope, then the privacy mechanism and return format. No wasted words for the amount of information conveyed.

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 audit tool whose safety profile is covered by annotations, the description conveys scope, the optional network check, and the A–F result. It could say a bit more about the result structure, but that is minor given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the burden, and it does: "(optionally) breached passwords via HaveIBeenPwned" explains exactly what the sole check_pwned parameter toggles. Minor gap in that it doesn't restate the default (false) 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?

Specific verb ("Audit") plus resource ("vault"), with an explicit enumeration of what is checked (weak, reused, expired/expiring, stale, unused, breached) and the output shape ("Graded A–F"). This clearly distinguishes it from siblings like audit_log (event log) and vault_status (state check).

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 audit purpose implies when you'd call it, but there is no explicit trigger or routing versus alternatives such as audit_log, vault_status, or find_credentials. Usage is inferable from the description rather than stated.

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 only give readOnly=false/openWorld=true/destructive=false; the description adds substantial behavioral context beyond them: the registered-host anti-exfiltration guard, response-body secret scrubbing, placeholder substitution rules, and auth-mode selection heuristics. This is exactly the security/behavior detail an agent needs.

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 core purpose, then dense supporting detail with no obvious filler. Slightly terse/run-on in the auth and placeholder clauses, but every sentence carries information.

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 an 11-parameter mutation tool with no output schema and no annotations covering permissions, the description covers behavior (scrubbing, host guard, substitution) but omits meaning of several params and any return-shape note. Adequate but with clear gaps.

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 0% schema coverage across 11 params, the description compensates well for `auth` (enumerating auto/basic/bearer/none/header/query with Jenkins/bearer nuance) and for placeholder use in url/headers/body, but `ref`, `method`, `timeout`, `json`, `allow_any_host`, and `follow_redirects` are left unexplained in both schema and description.

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+resource: 'Make an HTTP request authenticated with a stored credential, without exposing the secret.' This clearly distinguishes it from credential-management siblings and from run_with_credential, since the mechanism (authenticated HTTP call) is explicit.

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 how auth modes behave and the host allowlist guard, which implicitly tells the agent how to use it, but it never states when to choose this tool over run_with_credential or other siblings, nor any when-not conditions. Usage is only implied.

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, destructiveHint=false, and a closed world, so the safety profile is covered. The description earns credit by adding that only metadata is returned (names, types, usernames, URLs, aliases, tags, policies) — a meaningful disclosure that no secret values are exposed.

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 compact sentences with the core action front-loaded and no filler. The parenthetical field list is dense but justified given it defines the metadata-only scope.

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?

No output schema exists, but the description enumerates the returned metadata fields, and annotations cover safety. For a zero-required-parameter read tool this is close to complete; only filter-combination behavior is left unspecified.

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 0%, so the description must carry parameter meaning. It states both filters are optional and names them (type, tag), but adds nothing about tag matching semantics or whether the two filters combine with AND/OR.

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 every stored credential") and sharpens it with a scope qualifier ("metadata only") that separates it from a secret-revealing fetch. It doesn't explicitly contrast with the nearest sibling, find_credentials, so an agent could still hesitate between the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear triggering intent ("answer 'what creds / passwords / logins / keys do you have?'") and notes the optional type/tag filter. There is no explicit when-not guidance or named alternative, but the use case is unambiguous.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered externally. The description adds nothing beyond that: no ordering, pagination, retention window, or whether entries are restorable versus purge-eligible.

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 efficient sentence with the resource front-loaded and no filler. It is tight but borders on under-specified for a definition that carries nearly all the semantic load itself.

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 read with a full annotation safety profile and no output schema, the description is barely adequate. It omits the relationship to restore_credential and purge_credential, which are the obvious next actions on this data, leaving an agent to guess at the workflow.

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 and schema coverage is 100%, so there is nothing for the description to clarify. Baseline 4 applies with no meaningful gap.

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 (List) and resource (soft-deleted credentials), and the qualifier 'soft-deleted' implicitly separates it from list_credentials/find_credentials. It stops short of naming the natural follow-ups (restore_credential, purge_credential) that operate on this same set.

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 when-to-use guidance, no mention of prerequisites or alternatives, and no indication of what to do with the listed items. The agent must infer from the tool name alone that this is the trash/bin view rather than an active-credential listing.

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 mark this as a non-read-only, non-destructive mutation, and the description adds real behavioral context beyond that: it discloses the concrete effect (removing the key from the keychain) and the consequential asymmetry that unlocking requires the user. No permissions or reversibility details, but strong for its size.

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 short sentences with the action and its consequence front-loaded and zero filler. 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 tool with no output schema, the description covers what the agent needs: the action, its side effect, and the fact that recovery requires the user. No return format is described, but that is minor given the tool's simplicity.

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 no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly avoids inventing inputs and focuses on the action's effect.

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 ('Lock the vault') and immediately clarifies the effect with 'removes the key from the keychain.' It implicitly distinguishes itself from unlock_vault via the note that 'Unlocking needs the user,' giving an agent enough to tell the two apart.

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?

Usage is only implied by the word 'now' and the remark about unlocking requiring the user; there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Adequate for such a simple action but not instructive.

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 destructiveHint=true, so the destructive nature is known. The description adds two things annotations cannot convey: the operation is irreversible ('permanently destroy') and it 'always requires the user's approval' — a genuine workflow constraint. No return/error behavior is described, but the safety profile is 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 short sentences, zero waste, with the destructive consequence and approval requirement front-loaded. 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 single-purpose destructive tool with no output schema, the description covers the essential consequence and approval gate, and annotations carry the safety flags. The gap is the undefined 'ref' argument, which is the only input and is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single parameter 'ref' is documented nowhere. The description completely ignores it, leaving the agent to guess whether it is an ID, name, or path. With one undocumented parameter, the description must compensate and does not.

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 gives a specific verb (permanently destroy) and resource (a trashed credential), and the 'trashed' qualifier distinguishes it from delete_credential/restore_credential siblings, which operate differently. It stops short of explicitly naming those siblings as the routing alternatives.

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 precondition 'a trashed credential' implies this is only for items already in the trash, which is meaningful scoping. However, it never states the alternative (e.g., delete_credential to move to trash, restore_credential to recover), so the agent must infer the routing itself.

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=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive write. The description adds that the source is the trash, but says nothing about where the credential is restored to, whether it overwrites an existing credential, or what happens if the ref is not in the trash.

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?

One short, front-loaded sentence with no filler. It earns its place, though it is terse to the point of omitting needed 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?

For a simple one-parameter mutation with annotations covering its safety profile, the core purpose is conveyed. However, the unusable 'ref' parameter and unstated preconditions/effects leave the definition only minimally adequate.

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 required parameter 'ref' has 0% schema description coverage, and the description does not explain what 'ref' is (credential ID, name, or path) or how to obtain it. With one undocumented parameter, the description fails to compensate for the schema gap.

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 ('Restore') and resource ('credential') with a qualifying scope ('from the trash'), letting an agent distinguish it from delete_credential, purge_credential, and list_trash. It does not explicitly name a sibling, but the purpose 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?

Usage is only implied: the tool clearly applies to credentials previously moved to the trash, but the description names no alternative (e.g., purge_credential for permanent destruction) and states no precondition such as the credential first having to be deleted.

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 only say it is not read-only and not destructive; the description adds the important behavioral facts that this is a bulk, unfiltered action ('every') and that the effect is re-prompting on the next reveal. It does not mention confirmation or what is returned, but the core side effect is disclosed.

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?

One front-loaded sentence with no waste: verb, scope, and consequence in a single 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 zero-parameter tool with no output schema and simple annotations, the description covers what it does and its effect. Minor gap: it does not say whether the action is confirmable/undoable or how the agent observes success.

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?

There are zero parameters, so schema coverage is complete by definition and the baseline is 4; the description correctly implies a no-argument bulk operation.

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 (cancel/revoke) and a specific resource (time-boxed 'Allow for …' approvals), including the scope 'every'. It is distinguishable from credential CRUD siblings, though it never names a related sibling like run_with_credential to anchor it in the workflow.

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?

Usage is implied rather than stated: the purpose clause 'so the next reveal asks again' conveys why an agent would call it, but there is no explicit when-to-use/when-not guidance or named alternative.

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 mark this as a write (readOnlyHint=false) that is not destructive (destructiveHint=false). The description adds real behavioral context beyond that: the current value is preserved in history, which explains why the operation is non-destructive and reassures the agent it is reversible.

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 filler; every clause (verb, target fields, source version, non-destructive note) 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 two-parameter mutation tool with no output schema, the description conveys the core concept but leaves gaps: it never defines ref, doesn't say how to obtain a valid version (presumably credential_history), and gives no error or failure 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?

Schema description coverage is 0% and both parameters (ref, version) are bare. The description only weakly implies the meaning of version ('an earlier version') and says nothing about ref, so it fails to compensate for the total lack of parameter documentation.

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 gives a specific verb ('Restore') plus resource ('credential's username+secrets') and a scoping detail ('to an earlier version'). It is clear what the tool does, though it does not distinguish itself from the sibling restore_credential, which an agent could easily confuse with rollback.

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?

Usage is only implied by the phrase 'to an earlier version' – the agent can infer this is for reverting history, but no when-to-use guidance, prerequisites, or alternative (e.g. restore_credential vs update_credential vs purge_credential) is given.

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?

Goes well beyond the annotations: it names the injected variable scheme (KM_NAME/KM_USERNAME/KM_SECRET, KM_<FIELD>, KM_URL, KM_BASIC_AUTH), per-type extras (aws, database, ssh_key with a temp 0600 file that is shredded afterward), secret scrubbing including base64/url/hex encodings, and {{km.*}} placeholder behavior. This is exactly the behavioral context annotations cannot carry, and nothing contradicts readOnlyHint=false, destructiveHint=false, openWorldHint=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?

Dense and front-loaded: the core mechanism and scrubbing guarantee come first, then the variable conventions and an example. The type-extras list is long but each entry carries information an agent needs to build the command correctly.

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 high-complexity tool with no output schema and 0% schema coverage, the description supplies most of what's needed: invocation form, secret handling, encoding scrubbing, and per-type env layout. Gaps remain around timeout/cwd semantics and the meaning of ref and purpose, which are neither in the schema nor the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for 7 params, so the description must compensate. It explains env (mapping and template syntax like {{km.username}}:{{km.password}}) and stdin placeholders well, but says nothing about ref, command, cwd, timeout, or purpose, leaving a substantial share of parameters undocumented.

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+resource ('Run a bash command with the credential injected as environment variables') and a distinguishing property ('stdout/stderr are scrubbed of the secret'). An agent can immediately tell this apart from sibling tools like http_request or get_credential.

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?

Usage is implied by the mechanism (shell out with injected secrets), but the description never says when to prefer this over siblings like http_request or get_totp, nor lists prerequisites such as which credential refs are valid. It gives a concrete example but no when/when-not routing.

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 establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the burden is reduced. The description still adds genuinely non-obvious behavior: unlocking triggers a user-facing dialog and the passphrase never flows through the agent, which changes how an agent should sequence and narrate the call. It stops short of covering cancel/failure behavior or whether the call blocks.

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?

One sentence, zero padding, action front-loaded with the security mechanism in parentheses. 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 tool with annotations covering the safety profile and no output schema, the description supplies what matters most (mechanism and secret handling). Minor gap: no mention of what the agent/user sees on success, cancel, or a wrong passphrase.

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 (schema coverage 100%), so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies the passphrase is deliberately not an agent-supplied argument.

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?

Specific verb ('Unlock') plus resource ('the vault'), and the description goes further by naming the mechanism (a secure passphrase dialog). It is unambiguously distinct from the sibling lock_vault and from read-only tools like vault_status.

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?

Usage is only implied: an agent can infer this is the action for a locked vault, but the description never states when to call it versus alternatives (e.g., checking vault_status first) or what happens if the vault is already unlocked. Adequate but leaves the routing decision to inference.

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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds value beyond these: the previous secret value is preserved in version history for rollback, and loosening policy requires the user's approval (an auth/consent gate). These are meaningful traits the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short, front-loaded sentences with no filler; the partial-update rule and secret_source guidance come first. The final add_urls/add_aliases sentence is slightly advisory in tone but still 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 24-parameter mutation tool with no output schema and minimal annotations, the description is far too thin: it covers secret handling and URL/alias hints but omits the bulk of the parameter surface and rollback/authorization behavior for most fields. An agent cannot infer correct values for most arguments.

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 0% across 24 parameters, so the description carries the full burden. It only explains secret_source (five modes) and hints at add_urls/add_aliases, leaving ~22 parameters (policy enum values, set_secrets, rotate_days, generate_length, expires_at, etc.) undocumented in both schema and description.

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 clear verb+resource ('Modify a credential') and the critical partial-update semantics ('Only the arguments you pass change'), which distinguishes it from add_credential and delete_credential. It does not explicitly differentiate from siblings like rollback_credential or credential_history, which also mutate/examine a credential.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable when-to-use guidance: use secret_source to change the main secret, use add_urls/add_aliases when learning new references, and note that loosening policy requires user approval. No explicit when-not or named alternative tool, so it stops 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds what the call reports (init state, credential count, approval mode), but says nothing about cost, freshness, or whether state is cached, which would matter for a status probe.

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 that leads with the primary question the tool answers. It would be tighter if 'etc.' were replaced with the actual remaining fields or removed entirely.

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?

There is no output schema, so the description carries the burden of describing return values. It names three fields but trails off with 'etc.', leaving the agent unsure what the full response contains for a no-arg diagnostic tool.

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: no parameter semantics are 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?

Names a clear inspection verb and enumerates the specific facts returned (initialised/unlocked state, credential count, approval mode), which distinguishes it from lock_vault/unlock_vault siblings. The trailing 'etc.' leaves the scope slightly open-ended, but the core purpose 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?

No guidance on when to call this versus alternatives like health_report, audit_log, or list_credentials, and no prerequisites or context noted. The agent must infer usage purely from the name.

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