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

With no annotations, the description carries full burden and does disclose the core pipeline (local encryption with VaultKey + AAD, creation of sec_<ulid> records, generation of a .env.tpl template). However, it omits critical behavioral traits: whether the source file is modified or deleted, what dryRun and inPlace actually change, and any permission or irreversibility considerations for a mutation tool.

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

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

A single dense sentence that front-loads the extraction step and lists the produced artifacts without padding. Every clause carries information; it is not verbose.

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 mutating tool with no annotations, no output schema, and 0% parameter coverage, the description explains the processing flow but leaves the operational contract incomplete — especially the effects of dryRun/inPlace and what the tool does to the original file.

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 none of the four parameters are documented in the schema. The description only implicitly explains filePath (the file to absorb, e.g. .env) and says nothing about dryRun, inPlace, or vaultId, leaving the two behavior-altering flags uninterpretable.

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 specific verbs (extract, encrypt, generate) and resources (.env secrets, sec_<ulid> records, .env.tpl template), so the operation's purpose is unambiguous. It does not, however, differentiate itself from plausible siblings like vault_scan_workspace or vault_inject_env, which an agent might reasonably confuse it with.

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 statement of when to use this tool versus the many sibling vault_* tools, no prerequisites, and no exclusions. Usage can only be inferred from the described transformation pipeline.

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

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

With no annotations present, the description carries the full burden and does well: it declares read-only behavior, cryptographic tamper-evidence via HMAC-SHA256 hash chains, the required auth (ComplianceAuditor tokens), and an explicit scope exclusion. It stops short of describing pagination or return shape, but the safety and behavior profile is solidly conveyed.

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, front-loaded with the core purpose and then the scope constraint. No filler; every clause conveys signal.

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 behavioral picture is reasonably complete for a read query, but with 0% schema coverage this tool needs the description to explain its two filter/paging parameters, and it does not. No output schema exists, so return-value guidance is also absent, leaving a gap an agent would notice.

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 of the two parameters (limit, actionFilter) is mentioned in the description. The agent gets no meaning for 'actionFilter' beyond its name, and no hint that limit is capped at 500 or relates to result paging. The description fails to compensate for the coverage 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?

The description states specific verbs (query, hash-chain verify) and a precise resource (aud_<ulid> audit logs), with the verification mechanism (HMAC-SHA256) named. This clearly distinguishes it from the vault_* siblings, none of which deal with audit logs.

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 identifies the required token type (ComplianceAuditor) and notes that user/role/IdP admin mutations are excluded, which is useful scoping. However, it never states when to prefer this over alternatives or the conditions that trigger verification vs plain querying.

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

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

With no annotations, the description carries the full burden and does disclose the two-phase pattern and that the token is out-of-band. However, it omits the consequences of approving vs cancelling, token lifetime/single-use semantics, and any permission requirements for a tool that gates destructive operations.

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 filler; the action and its mechanism are stated immediately without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter gating tool with no annotations or output schema, the core is conveyed. Missing are the downstream effects of each branch, token behavior, and any failure modes the agent should anticipate when a token is invalid or expired.

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 compensate, and it partially does: it clarifies that the token is an 'out-of-band confirmation token' and that the confirm/cancel choice maps to the boolean. It adds no format, source, or validation detail for the token beyond the schema's minLength.

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 pair (confirm/cancel) and a specific resource (a pending destructive action or break-glass reveal), which is far more than a tautology. It does not name or differentiate against any sibling tool, so an agent must infer the relationship to vault_prompt_secret_oob or vault_delete_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?

Usage is implied by 'pending' and 'out-of-band confirmation token' – the agent can infer this follows a prior action that returned a token. But there is no explicit when-to-use, when-not-to-use, or named alternative, and no statement that a token must already exist.

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

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

With no annotations, the description carries the full burden and does well: it discloses a required permission, a human-confirmation gate, and the not-yet-executed return state. It omits whether deletion is permanent/soft and whether retrying is safe, 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 short sentences, action and scope front-loaded, with the precondition and failure branch following. 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 destructive, unannotated, output-schema-less tool, the description covers permissions, the confirmation gate, and the pending state. It leaves the completion path (which sibling confirms) and irreversibility unstated.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies the confirmationToken's role in the confirmation exchange, but leaves secretId and the token's format/lifetime undocumented, so compensation is only partial.

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+resource ('Delete a secret item from the vault'), immediately distinguishable from read siblings like vault_get_secret and vault_lease_secret. It does not name a specific sibling or overlap case, so it stops short of a 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?

States the prerequisite scope ('secrets:delete') and the out-of-band human confirmation requirement, and explains the unconfirmed branch via a returned confirmationToken. That gives clear context for when this tool is the right call, though it never names vault_confirm_action as the follow-up step.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the secret is generated locally via crypto.getRandomValues(), encrypted at rest with VaultKey and canonical AAD, and that only metadata { id, vaultId, version, handle } is returned — a critical fact implying the plaintext secret is never echoed back. It stops short of stating permissions, side effects on external systems, or reversibility (deletion via vault_delete_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?

A single dense sentence with the generate/encrypt/return sequence ordered logically and the return payload front-loaded at the end. No filler 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 an 8-parameter mutation tool with no annotations, no output schema, and 0% parameter documentation, the description does not do enough. It usefully discloses the return shape, but the agent still cannot determine how to meaningfully populate name, byteLength, encoding, vaultId, or folderId.

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 8 parameters, and the description explains none of them. Terms like byteLength, encoding, secretId, folderId, tags, and vaultId are left entirely for the agent to infer from JSON keys and enum values. This is the clearest gap in the definition.

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 compound verb (generate and store) plus the resource (secret) and the mechanism context (llm-vault-mcp), so the agent knows exactly what happens. It does not explicitly differentiate from siblings like vault_get_secret or vault_absorb_credentials, but the compound action is distinctive enough to stand on its own.

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 statement of when to choose this over vault_get_secret, vault_lease_secret, or any other sibling. There is no trigger condition, no 'use this instead of X' routing, and no prerequisites called out. The agent must infer intent from the name alone.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the default return shape (an opaque {{vault:sec_<ulid>}} handle) and that plaintext reveal is blocked absent break-glass and human confirmation. It omits auth/permission requirements and whether the access is audited, so it is not exhaustive.

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 dense sentences with no filler; the default behavior is front-loaded and the exception follows immediately.

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 usefully explains the returned surrogate handle. For a security-sensitive read tool with no annotations it is nearly complete, missing only auth/audit expectations and how a confirmation token is obtained.

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% across 4 parameters, so the description must compensate. It clarifies secretId semantics (sec_<ulid> form) and implicitly maps 'break-glass policy' and 'out-of-band human confirmation' onto breakGlassReason and confirmationToken, but never names or formats those parameters, leaving a real 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?

The description states a precise verb and resource: resolve a secret by its sec_<ulid> identifier and return a surrogate handle. That is specific enough to separate it from vault_lease_secret or vault_search, though it never names a sibling 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?

It gives a conditional gate on the raw-plaintext path (break-glass policy plus out-of-band human confirmation), which is useful when-not guidance. But it offers no explicit routing versus alternatives like vault_lease_secret or vault_prompt_secret_oob, so the usage context 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses two non-obvious traits: handle substitution into request headers and scrubbing of echoed credentials from response headers and body. However, it omits auth/permission requirements, logging or audit behavior, and error semantics for a security-sensitive outbound-call tool.

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

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

A single dense sentence that front-loads the action and folds in the two behavioral traits without waste. Tight and appropriately sized, though the injected syntax is only partially unpacked.

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 and no annotations, so the description must cover behavior and returns. It explains the distinctive secret-injection and scrubbing behavior well but says nothing about the response payload, error handling, or the meaning of the url/body/method parameters, leaving gaps for a 4-parameter proxy 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?

Schema description coverage is 0% with 4 parameters, so the description must compensate. It only implies the 'headers' parameter's role via the injection syntax and leaves url, body, and method (an enum) entirely unexplained beyond their names in 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?

States a specific verb (execute) and resource (outbound HTTP request), and adds the distinctive behavior of vault-handle injection plus credential scrubbing. The resource is unique among siblings, so an agent can tell it apart from vault_inject_env or vault_run_command, though 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?

The description explains what the tool does but gives no when-to-use, when-not-to-use, or alternative guidance. An agent must infer that this is for making HTTP calls that need secret injection versus the other vault tools that store or retrieve secrets.

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

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

With no annotations, the description carries the full behavioral burden. It does earn credit for two non-obvious disclosures: handles are resolved into the environment (rather than the command receiving raw secrets directly), and output is "scrubbed" before return. It says nothing about the fact that this executes an arbitrary subprocess, whether it requires approval, what privileges it runs with, or whether the command is silently mutated.

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, and the resolution mechanic leads ahead of the return behavior. It is dense rather than padded, though the run-on construction packs three distinct facts together without separation.

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 subprocess-executing tool with no annotations, no output schema, 0% parameter coverage, and a nested object parameter, this is too thin. The agent learns the core mechanic but not the side-effect profile, permission requirements, or what any of the four parameters actually accept.

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 four parameters, so the schema documents nothing and the description must compensate. The description only loosely implies that "env" holds the handles to resolve; it says nothing about command, args, cwd, or the fact that env is a nested string-to-string object. The nested-object structure is entirely 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?

The description names a specific verb ("Resolve"), its input ("opaque secret or lease handles"), its effect ("into a subprocess execution environment"), and its output ("scrubbed command output"). That is far more specific than a name restatement, but it never differentiates itself from the sibling vault_run_command, which an agent would plausibly confuse with this.

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 statement of when to use this tool rather than vault_run_command, vault_get_secret, or vault_lease_secret, and no mention of prerequisites or exclusions. The use case is only inferable from the mechanic described, which leaves routing between siblings to guesswork.

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

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

With no annotations, the description carries the full burden. It does disclose the hook's core behavior (blocks unencrypted secrets from staging), but for a mutation tool it omits critical side effects: whether install overwrites an existing hook, where the hook file is written, whether a git repository is required, and what status reports.

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 packs the action set and the tool's function with zero filler. Well-sized for a two-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate but incomplete for a hook-mutating tool with no annotations and no output schema. The agent still cannot tell what install modifies, whether removal is safe/idempotent, or what status returns, all of which matter 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?

Schema coverage is 0%, so the description must compensate. It enumerates the three action values, effectively documenting the action enum, but says nothing about workspaceDir — what it means, whether it defaults to cwd, or what happens if it is omitted (0 required params).

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 three specific verbs (install/check status/remove) against a specific resource (a zero-dependency git pre-commit hook for blocking unencrypted secrets). No sibling tool touches git hooks or staging, so the agent can tell it apart immediately.

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 three actions imply usage (install the hook, check whether it's installed, remove it), but there is no explicit statement of when to prefer this over siblings like vault_scan_workspace, nor any prerequisites (e.g. must be run in a git repo, whether an existing hook is overwritten).

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

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

With no annotations, the description carries the full behavioral burden. 'Generate' implies the tool returns text rather than mutating a cluster, and 'zero-knowledge' hints at the security model, but it never confirms side-effect-free behavior, auth requirements, or whether existing manifests are overwritten. Significant gaps remain.

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 key output front-loaded and no wasted words. It is perhaps overly terse for the tool's complexity, but as raw conciseness it is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with no annotations, no output schema, and zero parameter documentation, the description is too thin. It states what is produced but not how the inputs shape the output or what the caller receives, which is the core of what such a tool needs to convey.

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, including the nested secrets array (secretKey, remoteSecretId, property) and fields like vaultId, storeName, secretName, apiEndpoint, targetNamespace, and workloadBindingId. The description adds no meaning to any of these, leaving the agent to infer their purpose 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?

The description gives a specific verb ('Generate') and names the exact resources produced (Kubernetes ESO SecretStore and ExternalSecret manifests), plus scope qualifiers ('ready-to-apply', 'zero-knowledge vault synchronization'). It is clearly distinguishable from the sibling vault_* tools, though it doesn't explicitly state why one would pick it over a generic template approach.

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 prerequisites (e.g., whether a Vault connection must exist first), and no mention of alternatives. Usage is only implied by the resource 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?

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: decrypted bytes are held in MCP memory, the handle has the lease_<ulid> form, and the buffer is zeroed automatically at TTL expiry. It omits permissions/auth requirements, whether the lease is single-use or shareable, and what happens if it expires mid-use, so it is only partially sufficient.

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 with zero filler; the acquisition behavior is front-loaded and the security lifecycle note follows. 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?

There is no output schema and no annotations, so the description is the only source of behavioral context, and it leaves gaps: it never says how the lease handle is subsequently consumed, that vault_revoke_lease can end it early, or what errors arise from an invalid secretId. Adequate but incomplete for a security-sensitive 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?

Schema description coverage is 0%, so the description must compensate and largely does not: secretId is never mentioned, and ttlSeconds is only alluded to via 'time-bounded' and 'TTL expiration' with no units, default (60), or max (900) noted. The TTL allusion adds a little meaning but leaves both parameters under-explained.

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 verb ('Acquire') and a specific resource (a lease_<ulid> handle holding decrypted secret bytes), which is far more than a restated title. It implicitly separates itself from vault_get_secret by framing the result as a lease handle rather than the secret itself, but it never names that sibling 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?

There is no statement of when to choose this over vault_get_secret, vault_search, or when to follow up with vault_revoke_lease. The nearest thing to guidance is the TTL behavior, which is a trait, not a usage condition.

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

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

With no annotations, the description carries the full burden, but it does add real value: 'decrypted' implies vault unlock/decryption is involved, 'accessible' implies permission-scoped results, and 'unique' implies deduplication. It still omits read-only confirmation, rate limits, and what happens when no vault is unlocked.

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 padding. It is efficient, though arguably too terse for an unannotated tool with an undocumented parameter.

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 annotations and no output schema, the description should describe both the scope selection via vaultId and the shape of the return. It conveys the return content ('unique decrypted tag labels') but leaves the optional-parameter behavior and read-only nature unstated.

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

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

Schema coverage is 0% and vaultId is undocumented in both places. The phrase 'across accessible vaults' weakly implies the no-vaultId case is a global listing, but it never states that vaultId narrows the listing to one vault, leaving the parameter's meaning to inference.

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 ('tag labels') with a clear scope ('across accessible vaults'). No sibling performs tag listing, so the tool is functionally distinguishable, though the description never explicitly contrasts itself with vault_search or 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?

There is no guidance on when to call this versus alternatives such as vault_search. The only implicit hint is that it is a discovery/listing operation, but no prerequisites 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?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: the secret is entered client-side via WebCrypto and never exposed in chat. However, it says nothing about blocking/async behavior, whether a stored secret is created, what happens to the other 6 parameters, or permissions.

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

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

A single front-loaded sentence with no filler, and the security-critical constraint is stated early. It is efficient, though a second sentence on usage or parameters would have earned more value.

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 no annotations, no output schema, and 0% schema coverage, the description covers the 'why' but omits essentially everything about parameters, storage side effects, and interaction flow. An agent could not invoke it correctly from this description alone.

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 and does not. It never explains name, tags, vaultId, folderId, secretId, description, or promptMessage, leaving every parameter 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 specific verb (prompt) plus the actor and mechanism (human operator, out-of-band, client-side WebCrypto), which is far more than a restatement of the name. It distinguishes itself conceptually from generate/store siblings, though it never names an alternative 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?

The phrase 'without exposing the value in chat context' implies when the tool is appropriate, but there is no explicit when-to-use, when-not-to-use, or routing to siblings like vault_absorb_credentials or vault_generate_and_store_secret. Usage is left 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?

No annotations are supplied, so the description carries the full burden. It does disclose a real behavioral consequence beyond the name: the in-memory buffer is immediately zeroized, signalling an irreversible destructive effect. It omits auth requirements, idempotency, and what happens if the lease is already expired or unknown.

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 tight sentence that front-loads the action and ends with the consequence. No filler, no 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 one-parameter mutation with no annotations and no output schema, the description covers the essentials of what happens but leaves error behavior, permissions, and post-revocation state unaddressed. Adequate but with clear gaps given the destructive nature of the 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 0% for the single required leaseId, so the description must compensate. It partially does by revealing the expected identifier format (lease_<ulid>), but adds no detail on where that handle comes from or what form it takes beyond the prefix.

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 (revoke), a specific resource type (an active lease_<ulid> handle), and the immediate effect (zeroize in-memory buffer). It is clearly distinct from read-oriented siblings like vault_get_secret or vault_lease_secret, though it never names or contrasts a sibling 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?

The word "Explicitly" faintly hints that leases may otherwise be revoked implicitly (e.g. on expiry), but there is no statement of when to call this versus letting a lease lapse, no preconditions, and no named alternative. The agent must infer the entire usage 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?

With no annotations, the description carries the full burden, and it does disclose one genuinely valuable trait: stdout/stderr are scrubbed for raw, Base64, and URL-encoded secret leaks. It omits other consequential behavior for a subprocess executor — permission requirements, sandboxing, exit-code/timeout handling, and whether the command runs with the caller's privileges.

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 dense sentence that front-loads the action and immediately follows with the injection mechanism and the scrubbing guarantee. Every clause carries information; only the URL/Base64 enumeration feels slightly list-heavy.

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 security-sensitive subprocess executor with no annotations, no output schema, and 0% parameter documentation, the description covers the two most distinctive behaviors (handle injection and leak scrubbing) but leaves permissions, isolation, and return/exit 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% across 4 parameters, so the description must compensate, and it largely does not. It clarifies the semantics of 'env' (values may contain {{vault:sec_<ulid>}} / {{vault:lease_<ulid>}} handles), but says nothing about 'command', 'args', or 'cwd'.

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 ('Execute a subprocess') and adds the distinctive mechanism (vault handle injection into env vars). It does not, however, explicitly differentiate itself from the close sibling vault_inject_env or vault_http_proxy, so an agent must infer the distinction.

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 handle syntax hints at when the tool is applicable (you hold sec_/lease_ handles), but there is no explicit when-to-use, when-not-to-use, or naming of alternatives such as vault_inject_env. An agent gets no routing guidance between the sibling execution/injection 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?

With no annotations, the description carries the full burden. It does disclose the return shape (line numbers, entropy, suggested {{vault:sec_<ulid>}} handles), which implies a non-mutating detection pass, but it never states that nothing is written or uploaded, nor any auth or scope requirements for reading workspace files.

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 enumerates inputs first and outputs second, with no filler. It is dense but every clause carries information; a mild structural break between inputs and outputs would read better.

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, no annotations, and 4 fully undocumented parameters. The description covers the scan targets and the finding shape, but an agent still lacks parameter semantics, safety guarantees, and any indication of what happens on large or binary inputs.

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 compensate. It maps path→workspace files, stagedOnly→git staged diffs, and content→direct text, and mentions entropy (hinting at minEntropy), but gives no format, defaults, or precedence rules for the four parameters.

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 ("Scan") plus three concrete input sources (workspace files, git staged diffs, direct text content) and a clear target (unencrypted credentials). It is distinguishable from vault_search/vault_absorb_credentials by being a detection-only scan, but it never names an alternative sibling to sharpen the boundary.

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 three scan modes implicitly map to path/stagedOnly/content, so the agent can infer which mode to pick, but there is no explicit when-to-use guidance, no prerequisites, and no statement of when to prefer this over vault_absorb_credentials.

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

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

With no annotations to lean on, the description carries the full burden and does disclose real behavior: metadata is decrypted locally (client-side processing) and results are 'safe summaries with opaque handles' rather than plaintext secrets, scoped to 'accessible' vaults. It still omits pagination, result limits, and any auth/permission details, so it is not fully transparent.

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 with no filler; the search scope and facets come first, and the return-handling behavior second. 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 4-parameter tool with 0% schema coverage, no annotations, and no output schema, the description gives an agent the gist of what comes back but not enough to call it precisely: facet combination semantics, pagination/limits, and the role of vaultId are all 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% across 4 parameters, so the description must compensate. It maps three concepts—keyword (query), tag blind index (tag), and folder (folderId)—but leaves vaultId unexplained and does not say whether multiple facets combine as AND or OR, so compensation is partial.

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 (search) and resource (accessible vaults), and enumerates the three search facets: keyword, tag blind index, and folder. The phrase 'returns safe summaries with opaque handles' implicitly contrasts it with fetch-style siblings like vault_get_secret, but no sibling is named explicitly, so differentiation is inferable rather than stated.

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 a discovery-then-fetch workflow by describing search facets and safe summaries, but never states when to use this tool versus vault_get_secret or vault_list_tags, nor any prerequisites or exclusions. Usage is reasonably self-evident for a search tool but not spelled out.

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

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

No annotations are provided, so the description carries the full burden. 'Inspect' strongly implies a non-destructive read and it discloses the categories of data surfaced, but it says nothing about auth requirements, side effects, or whether it can be called when no agent is running.

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 dense, front-loaded sentence with no filler; the verb leads and the returned fields follow immediately.

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 status tool with one optional parameter and no output schema, listing the returned data categories compensates well for the missing output schema. The only real gap is the undocumented socketPath input.

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 optional socketPath parameter has 0% schema coverage, and the description does not explain it. The phrase 'socket path' appears only in the list of inspected outputs, which is more likely to confuse the agent about whether it is an input than to clarify the parameter.

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 ('Inspect') and resource ('active SSH agent status'), and enumerates the concrete contents returned (Ed25519 signing keys, socket path, approval policies). It is distinguishable from the generic vault_status sibling, though it never names that distinction 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?

No when-to-use guidance, no prerequisites, and no mention of when to prefer this over vault_status or any other sibling. The agent must infer that this is the SSH-agent-specific diagnostic.

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

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

With no annotations and no output schema, the description carries the full burden, and it does disclose the salient return contents, including the identity format and the fact that OS keychain unlock state is reported (a failure-relevant signal). It stops short of stating permissions/auth requirements or that it is strictly side-effect free.

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 the verb first and a dense enumeration of reported fields. Every clause adds information; nothing is padding or restated from 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 zero-parameter, no-annotation, no-output-schema tool, the description supplies the return-surface detail an agent needs to interpret the result. Minor gaps remain around read-only guarantees and whether an unauthenticated call returns an error versus a status payload.

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 the baseline is 4. The description correctly focuses on what is returned rather than implying any input, and there are no parameters left 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 ('Query') and resource ('active MCP vault connection status') and enumerates the fields reported (agt_<ulid> identity, keychain unlock state, permission scopes). This makes it clearly a read-only diagnostic, distinguishable in substance from vault_get_secret or vault_search, though it never names a sibling 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?

Usage is only implied: an agent can infer this is the pre-flight check to run before vault operations, especially given the keychain-unlock-state mention. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as vault_ssh_agent_status.

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