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

With no annotations, the description carries the full burden and does so thoroughly: it explains that secrets are never returned, the broker attaches and strips them, the entry controls attachment, and Tier 1/Tier 2 approval behavior is described. It also discloses signed operations and complex stamped-key signing behavior, including owner approval for recipes.

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 front-loaded with the core purpose and then structured around the two calling modes. It is long and dense, but the length is largely justified by the tool's complexity and security-sensitive behavior.

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

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

Given the absence of annotations and output schema, the description provides enough context to invoke the tool correctly: it covers secret handling, two call modes, approval tiers, operation signing, and secret placement. Nothing critical for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so the schema already documents parameters extensively. The description still adds meaningful semantics beyond the schema by explaining the request-vs-operation_id choice and that the entry, not the caller, decides how the secret is attached.

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 first sentence states a specific verb and resource: call a web service using a vaulted secret that is never exposed. It clearly scopes the tool to brokered HTTP calls, but it does not explicitly differentiate from siblings like vault_sign, vault_pay, or vault_ssh_exec beyond naming vault_entries_list.

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

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

It clearly explains the two invocation modes: a self-described request or a named operation with typed args. It also points to vault_entries_list for discovering operations, giving useful context, but it does not explicitly state when to use this tool instead of the specialized sibling tools.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the returned fields and an important security invariant ("Never a secret's value — no tool returns one"), which preempts an agent hunting for values elsewhere. It omits auth/permission requirements and whether the listing is complete or paginated.

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

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

Two sentences, front-loaded with the action and scope, followed by the returned-field taxonomy. The em-dash list of tool mappings is dense but each element is necessary for routing to the correct sibling.

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 describe the return shape—which it does, covering ID, name, tier, secret kind, and signed operations. It does not address pagination, ordering, or empty-result behavior, a minor gap for a discovery 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?

Zero-parameter tool, so the baseline applies; the description correctly conveys that no filtering input is accepted. The optional nature of the inline filter parameters is assumed to be captured in the schema descriptions.

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

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

Specific verb+resource ("List the vault entries") with a stated scope ("this agent may use") that cleanly separates it from the four action siblings. It also enumerates the fields returned, so an agent knows exactly what discovery yields.

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?

By mapping secret kinds to their consumer tools (web-service → vault_call, SSH → vault_ssh_exec, wallet → vault_pay, signing key → vault_sign), it implicitly tells the agent this is the discovery step before invoking those tools. It never states the exclusion explicitly (e.g. "call this before X"), so guidance is strong but inferred.

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

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

With no annotations, the description carries the full behavioral burden and does so well: the key is never returned, USDC only on four named chains, payments inside owner rules are signed immediately, and anything outside allowed payees or the daily limit waits for owner approval. It also discloses the polling pattern: call again with the same payment to keep waiting.

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 action and stays dense with no filler. The opening phrase is slightly awkward and the approval-waiting clause is packed into the same paragraph, but every sentence adds useful 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?

Given four parameters, no output schema, and no annotations, the description covers the critical gaps: what the tool returns (the header to send on retry), chain and currency restrictions, the approval flow, and the retry behavior when approval is pending. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by saying payment_required can also be a v1 402 body, and that purpose is shown to the owner if approval is requested. accept_index is not elaborated in the description but is adequately covered by 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 and resource: pay an x402 402 Payment Required from a vaulted wallet whose key is never exposed. This is clearly distinct from sibling tools like vault_sign or vault_call, which do not handle x402 payment flows.

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?

Explains exactly what to pass (the PAYMENT-REQUIRED header, decoded JSON, or v1 402 body) and what to do with the result: retry with the returned header. Also tells the agent how to keep waiting when owner approval is pending. It does not explicitly name alternatives or exclusions versus vault_sign, which keeps it from a 5.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that the key is never returned, that every signature requires owner approval, that the owner sees the data plus its sha256, the 256 KiB ceiling, and exactly what is returned (signature, public key, algorithm). It stops short of describing rejection/failure behavior or what happens when the size limit is exceeded.

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 sentences, zero waste, with the core action and the strongest constraint (key never returned) front-loaded. Every sentence carries a distinct fact: action, approval model, return values, size limit.

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 non-destructive-looking signing tool with no output schema and no annotations, the description supplies return fields, the approval model, and size constraints — enough to call it correctly. The remaining gap is error/rejection behavior and whether signing is deterministic, which an agent would want for retry logic.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: the 256 KiB cap on data and the 64 KiB threshold at which text is shown to the owner in full. `purpose` is reinforced as owner-visible, though its operational effect is already 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 and resource ("Sign data with a vaulted signing key") and immediately scopes it with the constraint that the key is never returned. That is clearly distinct from sibling operations like vault_call, vault_pay, and vault_ssh_exec, so an agent can select it without reading further.

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 purpose (sign a payload held by the vault) rather than explicitly stated; there is no guidance on when to prefer this over vault_call or the other siblings, and no exclusions. The approval flow is described, which gives the agent context on cost/latency, but it is not framed as a selection rule.

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 at all, the description carries the full burden and does so thoroughly: the key is never written to disk nor returned, the agent socket lives only for the call, every signature is audited with fingerprint and host, and the host is validated server-side so remote_argv cannot redirect the connection. It also pre-empts the obvious injection attempt explicitly, which is exactly the kind of behavior an agent cannot infer from schema.

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

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

Front-loaded with the action, then layered security constraints; every sentence adds new information. It runs four short paragraphs where three would suffice, but there is no filler to cut.

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

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

Covers the security and authorization model completely for a 7-parameter mutation-adjacent tool with no annotations. The remaining gap is the return shape — with no output schema, the description never says whether the caller gets stdout, stderr, and exit status, which matters for a command-execution 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 coverage is 100%, so each of the 7 parameters is already documented in the schema. The description only adds that remote_argv and rsync_args are mutually exclusive paths and that destination must match the entry's ssh_hosts — useful reinforcement but largely a restatement, so baseline 3 applies.

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

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

States a specific verb and resource — run a command on a remote host or rsync files — and pins the mechanism: a vaulted SSH key that never leaves the broker. This clearly separates it from siblings like vault_sign and vault_pay, which do not execute remote commands.

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 scope of use is explicit (remote exec or rsync against an allowlisted host) and it states a hard when-not: 'An entry with no ssh_hosts authorises nothing.' It never names a sibling as the alternative path, so the routing guidance is clear but not fully comparative.

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