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

No annotations are provided, so the description bears the full behavioral burden. It usefully discloses ordering (newest last) and the redaction policy (names and redacted commands, never values), but it says nothing about permissions, rate limits, pagination, or whether the read is safe/reversible beyond the implied 'query' verb.

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 no filler. The ordering and redaction constraints are front-loaded and every clause carries information the agent needs.

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-optional-param read tool with no output schema, the description discloses the return shape (names and redacted commands) and ordering, which is what an agent most needs. The only minor gap is that 'recent' is undefined and no time-window behavior is given.

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

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

The single parameter has 100% schema coverage including bounds (1-500) and default (50), so the schema does the heavy lifting. The description adds no additional meaning about the limit parameter, which matches the baseline of 3 when coverage is high.

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 (audit entries) with scoping ('recent') and ordering ('newest last'). It is clearly distinguishable from secret/shell/rule siblings by name, but it does not explicitly differentiate itself from any alternative or explain what an audit entry is.

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 offers no when-to-use or when-not-to-use guidance, and does not reference any alternative such as secret_list or rule_list. Usage is only implied by the tool name and resource.

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. 'List' reasonably implies a read-only operation, and the parenthetical discloses a non-obvious behavior — that results include statically computed warnings (e.g. rules matching every directory). However, it says nothing about permissions, pagination, or result 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?

A single, front-loaded sentence with no filler. The parenthetical example earns its place by illustrating the warning concept concretely.

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 no-parameter read tool with no output schema, the description conveys what is returned (rules plus static warnings) well enough to call it correctly. It could go slightly further on output shape, but nothing essential 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?

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a 0-param tool is 4. The description adds nothing misleading about inputs.

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 injection rules') and adds scope via 'with static warnings,' which tells an agent what the result set contains. It does not explicitly differentiate itself from the sibling rule_validate, but the verbs are distinct enough that confusion is unlikely.

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, when-not-to-use, or alternative guidance is given. The agent must infer that this is the read/inspection counterpart to rule_validate purely from the name; nothing in the description confirms that or states prerequisites.

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: 'statically' signals no side effects or execution, and it discloses the specific finding categories (unknown secret refs, unreachable/shadowed rules, inject-everywhere, requireConfirm notes, union mergeStrategy risk notes) plus a severity note. It stops short of stating explicitly that nothing is modified.

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 action and then lists findings. The parenthetical catalog is dense but every item is informative, so little is wasted, though the enumeration could be shortened with a summary phrase.

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 must convey what comes back; it does so by naming the finding categories and flagging high-severity and risk-note outputs. That is sufficient for an agent to interpret a call, with only minor gaps about result format/ordering.

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 no parameter semantics to document; the schema coverage is 100% and the baseline for a no-param tool is 4.

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 verb (statically validate) and resource (rules.yaml) and enumerates the exact class of outputs it produces. It is clearly distinguishable from siblings like rule_list, which merely enumerates rules rather than analyzing them.

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 'statically' implies this is a non-executing, pre-flight check, which hints at when to use it, but there is no explicit guidance about when to run it versus rule_list or what preconditions apply. Usage is implied 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?

With no annotations, the description carries the full burden. It usefully discloses a non-obvious side effect—unregistering from rules.yaml—but omits other critical behavioral context such as whether deletion is permanent, what permissions are required, or what happens if the secret is in active use.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core action and an important side effect with no wasted words.

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

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

For a simple one-parameter delete tool with no annotations or output schema, the description covers the action and side effect but leaves significant gaps: no parameter details, no warning about irreversibility or permissions, and no return information.

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

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

The schema has zero description coverage for the single 'name' parameter. The description does not compensate by explaining what the name represents (e.g., its format, source, or relation to rules.yaml), leaving the agent without guidance beyond the basic type.

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

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

The description states a specific verb (Delete) and resource (a secret), and adds the side effect of unregistering from rules.yaml. This clearly distinguishes it from siblings like secret_set (create/update), secret_list, and secret_probe, which serve different operations.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, when not to use it, or any prerequisites. It merely states what the tool does, leaving usage entirely to inference 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?

With no annotations, the description carries the full burden and does disclose two meaningful behaviors: it returns names plus metadata fields (backend ref, resolvable) and it deliberately withholds secret values. It does not state read-only safety, permission requirements, or how many entries are returned, so it falls short of 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?

A single sentence that front-loads the action and resource, then adds the two facts an agent most needs (what metadata comes back, what is not returned). 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 list tool with no output schema, the description conveys the return shape (names + backend ref + resolvable) and the critical exclusion of values. It could go one step further by stating the read-only nature or pagination/size behavior, but nothing essential to correct invocation 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?

The tool takes zero parameters (empty object schema), so there is no parameter semantics to explain and the baseline is 4. Nothing in the description misrepresents the parameter surface.

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 verb and resource ("List registered secret names") and immediately bounds the result set with "with metadata (backend ref, resolvable)" plus the negative scope "Never returns values." This cleanly separates it from siblings like secret_probe (which presumably retrieves values) and secret_set/secret_delete.

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 "Never returns values" clause implies the tool is for enumeration only and that value retrieval belongs to a sibling, but no alternative is named and no explicit when-to-use or prerequisite is stated. Usage is inferable rather than guided.

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 the return shape {ok, masked} and a masking constraint, but omits side-effect/read-only status, required permissions, and failure behavior.

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

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

Two concise sentences with zero waste. The purpose is front-loaded, and the return/masking constraint follows efficiently.

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 probe with no annotations or output schema, the description gives purpose and return shape. It remains incomplete on usage routing, permissions, and failure behavior, so it is only moderately complete.

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

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

The schema has only one required string parameter with 0% description coverage. The description adds that the parameter represents a secret ref, which is meaningful, but it does not explain format, validation, or examples.

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: checking whether a secret ref can be resolved. It is clear on its own, but it does not name or distinguish itself from siblings such as secret_list or secret_set, leaving routing to inference.

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, prerequisites, or alternatives are given. The description says what the tool does, but not when an agent should choose it over secret_list or secret_set.

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 does deliver real behavioral facts: the value is persisted, never echoed back, and the name is registered in rules.yaml as a ref only. It still omits overwrite semantics for an existing name and any auth/backend-failure behavior.

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

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

Two compact sentences, front-loaded with the core action, and each clause adds non-redundant information (persistence, non-echo, rules.yaml side effect).

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 for a 3-param mutation tool with full schema coverage, but with no annotations and no output schema the description should cover more of the write's side effects and failure modes. It covers the headline behaviors without being complete.

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

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

Schema coverage is 100%, so the schema already documents name, value, and ref with examples. The description adds the ref-only registration detail but no field-level syntax beyond what the schema provides; 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 ("Store") and resource ("a secret value") plus the destination ("configured backend"). The store/delete/list/probe distinction from siblings is obvious from the operation named, though no sibling is called out 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 guidance on when to use this versus secret_probe, secret_list, or secret_delete, and no prerequisites such as auth or backend-configured state. Usage is only implied by the verb.

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 substantial work: it discloses output redaction of injected secret values, hard-blocked command patterns with examples, and the secret-injection model. It still omits exit-status behavior, timeouts, and the side-effect profile of arbitrary command execution, which matter for a mutation-capable 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?

Four tight sentences, front-loaded with the core action and immediately followed by the safety-relevant behavior. No filler or repetition of the tool 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 command-execution tool with no annotations and no output schema, the description covers the safety profile (redaction, hard blocks, env-injection model) that an agent most needs. Remaining gaps are return-shape and failure-mode details, which are minor given the absence of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that secrets cannot be passed as env params and are injected only by rule reference — which is exactly the semantic governing 'profile' and 'extraEnv'. It does not, however, clarify rule/profile matching syntax or allowlist contents.

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 ('shell command') plus a scoping qualifier ('one-shot') that cleanly separates it from the shell_session_* siblings. An agent can distinguish it from shell_proxy_* and session tools without opening any 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 'one-shot' framing and the explicit constraint that there is no free-form env parameter (secrets only by rule reference) give clear context for when this tool is appropriate. It stops short of naming shell_session_open/send as the alternative for persistent or interactive work, so the routing is implied 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?

With no annotations to lean on, the description carries the full burden and does well: it declares the tool is a read-only enumeration and, critically, that output is metadata-only and 'Never includes values' — a security-relevant guarantee about secret redaction that structured fields do not convey. It stops short of stating pagination or whether stopped-but-registered proxies appear.

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 sentence that front-loads the action and resource, then qualifies the return shape and the security constraint. Every clause earns its place with 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?

Although there is no output schema, the description enumerates the returned fields (id, port, upstreamHost, secret NAME, expiry, request count) and the exclusion of values, which is exactly what an agent needs for a zero-parameter read 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 to document; the baseline for a parameterless tool is 4. No parameter semantics are needed or missing.

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 ('running credential proxies') and even enumerates the returned metadata fields. It is immediately distinguishable from the sibling mutation tools shell_proxy_start and shell_proxy_stop.

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 listing intent is self-evident from the name and verb, so usage is implied, but the description offers no explicit guidance on when to reach for this versus shell_proxy_start/stop or when to prefer it over alternatives. No exclusions or prerequisites 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 so well: random localhost port, in-memory-only secret injection into a configured header, automatic stop after TTL (default 300s), and an explicit guarantee that the secret is never returned. These are exactly the behavioral traits 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?

Three tight sentences, front-loaded with the action and endpoint, then the injection model and lifetime. No sentence is filler; every clause adds operational 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?

No output schema, and the description covers the key return caveat (secret never returned), but it doesn't explicitly state that the chosen port is surfaced to the caller—an agent must infer how to learn <port>. Otherwise complete for a two-parameter lifecycle 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% (baseline 3), and the description adds real meaning: `id` maps to a `proxies` entry in config.yaml, and `ttlSeconds` overrides a documented default of defaults.proxyTtlSeconds=300s. This goes beyond the schema's terse 'TTL override (seconds)'.

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 ('Start a credential-injecting reverse proxy') scoped to a `proxies` entry, which clearly distinguishes it from siblings like shell_proxy_stop and shell_proxy_list. An agent can identify exactly what this tool produces 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?

Explicitly tells the agent how to use the result: 'Point commands at http://127.0.0.1:<port> instead of the real API host.' This gives clear operational context, but it does not state when to prefer this over alternatives (e.g. shell_exec with a secret directly) or any preconditions.

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, and it discloses almost nothing: whether the operation is idempotent, what happens to in-flight sessions or credentials, what errors occur if the proxy is not running, or permission requirements are all absent. 'Stop' signals a state change but no consequences.

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 verb and resource are front-loaded. 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 mutation tool with no annotations and no output schema, the description is too sparse: it omits where proxyId comes from, what stopping does to the proxy's credentials/sessions, and what success or failure looks like. An agent can attempt the call but cannot predict its effects.

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

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

The single parameter proxyId has 0% schema description coverage, and the description only implies it identifies the running proxy without giving format, source (e.g., shell_proxy_list), or behavior for an invalid id. This leaves the parameter under-documented.

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 (Stop) and resource (running credential proxy), which lets an agent distinguish it from shell_proxy_start and shell_proxy_list. It does not explicitly name or contrast those siblings, so it falls 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?

The phrase 'a running credential proxy' implies the proxy must be active, but there is no guidance on when to stop versus start/list, no prerequisites, and no alternatives named. Usage must be inferred from the tool 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 burden and does disclose the key destructive side effect: the process is killed and injected secrets are destroyed. It omits other behavioral facts an agent needs, such as permissions required, behavior on an already-closed session, and whether the operation is idempotent.

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 zero filler: the action comes first and the consequence follows. Nothing could be removed without losing 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?

For a one-parameter tool with no annotations and no output schema, the description covers the primary destruction semantics but leaves error cases, auth requirements, and confirmation of success unexplained. It is minimally adequate rather than complete.

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

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

One required parameter with 0% schema description coverage, and the description never names or explains sessionId. The phrase "Close a session" makes the parameter's meaning inferable, but no format, source, or valid-value context is added beyond the schema.

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

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

States a specific verb and resource ("Close a session") plus a concrete consequence (process killed, injected secrets die). However, it does not distinguish this from the overlapping sibling shell_session_revoke, leaving ambiguity about which teardown operation to pick.

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 explicit when-to-use guidance, no prerequisites, and no named alternative. An agent must infer from the description that this is the terminal teardown step, and gets no help choosing between it and shell_session_revoke.

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. It does add one genuinely useful behavioral fact — 'metadata only' — signalling that session output/buffers are NOT returned here, which steers the agent to shell_session_send for content. However, it says nothing about permissions, ordering, or whether sessions from other users appear.

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 scope stated before the parenthetical detail. Every element earns its place; there is 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 zero-param, read-only listing tool with no output schema, the description compensates by enumerating the returned metadata fields (id, cwd, pty, ttl, timestamps), which is the key missing structured information. Only minor gaps remain (auth/scope, ordering).

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. Nothing in the description is needed to explain inputs, and it adds the useful note that outputs are metadata fields rather than live data.

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 ('live sessions'), and the parenthetical enumerates exactly what is returned (id, cwd, injected names, pty, ttl, timestamps). This cleanly separates it from the mutating siblings shell_session_open/send/close/revoke without needing their schemas.

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 discovery step before send/close/revoke, but the description never states when to call it versus alternatives or any preconditions. No explicit when/when-not guidance is present.

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 substantial work: it discloses the PTY-vs-child_process fallback plus the `pty` response field, that secrets are injected once at creation per matching rule, and idle-TTL termination semantics. Missing only auth/permission requirements and failure behavior.

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

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

Two dense sentences with the core action front-loaded; the PTY parenthetical and the TTL precedence note carry real information. Slightly heavy on embedded parentheticals but no wasted prose.

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 session-opening tool with no annotations and no output schema, the description covers lifecycle, secret injection, and TTY behavior well, but omits how the session is subsequently driven (shell_session_send) and any authorization constraints, leaving the agent to infer the interaction model.

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 goes beyond it by explaining ttlSeconds precedence (rule ttlSeconds overrides defaults.sessionTtlSeconds), which adds meaning not present in the schema field text.

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: 'Open a persistent shell session.' The word 'persistent' implicitly distinguishes it from the one-shot sibling shell_exec, but it never names or contrasts with any 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?

No when-to-use guidance is given. With shell_exec, shell_session_send, and shell_session_close in the sibling set, the agent must infer from the tool name alone that this is the session-establishment step rather than one-shot execution. No exclusions, prerequisites, or alternatives 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?

No annotations are provided, so the description carries the full burden, and it does disclose strong behavioral facts: the kill is immediate, the replacement session has no injected secrets, and a new sessionId is returned. It omits whether the old sessionId is invalidated, whether any state/workspace carries over, and permission requirements.

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, front-loaded with the action and the secrecy constraint, then usage, then return value. 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 single-parameter tool with no output schema, the description covers action, condition, side effect (no secrets), and return value. It leaves open the fate of the old session and whether dependent state is inherited, but the essentials are present.

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

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

Schema description coverage is 0% for the single sessionId parameter, and the description only mentions 'sessionId' as a return value, not clarifying that the input is the compromised session to be destroyed. The intent is inferable but not explicit.

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 ('kill a session and rebuild a fresh one') plus a distinguishing scope qualifier ('WITHOUT any injected secrets'), which separates it from the plain close/list siblings. An agent can tell what this does 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?

Gives a clear triggering condition ('Use when a session may have been compromised'), which is exactly the context an agent needs. It does not name alternatives such as shell_session_close or say when NOT to use it, so it falls 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?

With no annotations the description carries the full burden, and it does valuable work: it discloses that stdout/stderr are merged and redacted before return, that dangerous commands are blocked per security.dangerousCommands, and that the result shape is {output, exitCode}. It omits session lifecycle/timeout behavior and permission requirements, but the security-relevant traits are unusually well surfaced.

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 action and followed by security behavior and return shape. Every sentence carries information; nothing is 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?

With no output schema, the description correctly summarizes the return value, and it covers the key behavioral caveats (redaction, blocking). The remaining gap is the relationship to sibling session tools (open/close/revoke) and what happens if the session is stale.

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% with two required parameters, yet the description adds little: 'persistent session' loosely hints that sessionId identifies an existing session, and 'command' is self-evident from context. It provides no detail on command format, shell semantics, or how sessionId is obtained.

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 ('Send a command to a persistent session'), which clearly implies it operates on an already-open session rather than a one-shot exec. It stops short of naming the sibling it differs from (e.g. shell_exec or shell_session_open), 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?

Usage is only implied: the required sessionId and the phrase 'persistent session' suggest a session must already exist, but the description never states the shell_session_open prerequisite or contrasts with shell_exec for stateless execution. No explicit when/when-not guidance is given.

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