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

With no annotations, the description carries the full burden of disclosing behavior. It transparently communicates a critical side effect: closing the shell also closes its managed process tree, which is substantive context beyond the schema. It does not address idempotency or whether the operation is reversible, but the core destructive behavior is clear.

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 efficient sentence that front-loads the verb and resource, then states the important side-effect scope. There is no wasted text or repetition of schema content.

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 tool is simple and has an output schema, so the description need not explain return values. However, it omits practical context such as the relationship to shell_open, how shell_close differs from shell_signal, and what happens when an invalid or already-closed shell_id is provided. It is adequate but not fully 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 description coverage is 0%, and the description does not explain shell_id, where it comes from, or how it should be obtained. The parameter name is self-explanatory to a degree, but the description adds no semantic value beyond the schema's property name and constraints.

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

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

The description uses a specific verb ('Close') and a clear resource ('persistent shell') while also naming the scope of the side effect ('managed process tree'). This clearly distinguishes it from sibling tools such as shell_open, shell_exec, and shell_signal, which have different actions.

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 guidance on when to invoke this tool versus alternatives like shell_signal, nor does it mention prerequisites such as first opening a shell with shell_open. The usage context 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?

No annotations are provided, so the description carries the full burden. It does not disclose that commands may mutate state, that the shell persists between calls, how output is returned, or that errors can occur mid-command. 'Execute one bash command' only states the action, not the behavioral 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?

The description is a single concise sentence with no fluff or redundant detail, and it is front-loaded with the core action. It is under-specified overall, but as far as conciseness alone it earns high marks.

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 that this is a shell execution tool with potentially destructive side effects, no annotations, and five parameters, the description is too thin. It omits prerequisites (an existing shell), behavioral guarantees, and guidance around the timeout/output parameters. The presence of an output schema reduces the need to describe return values, but not these other aspects.

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 the description adds no parameter-level meaning beyond the raw property names. It does not clarify shell_id's relationship to an existing session, or the meaning of yield_ms, timeout_ms, or max_output_bytes. With zero schema coverage, this is insufficient.

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

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

The description uses a specific verb 'Execute' and names both the resource ('one bash command') and the context ('persistent shell'). This clearly distinguishes it from sibling tools like shell_open, shell_write, and shell_read, which have different purposes.

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

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

The description gives no guidance on when to use this tool versus shell_write or shell_read, and no mention that shell_id must already exist (e.g., from shell_open). Usage context is only implied by the word 'Execute.'

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 present, so the description must disclose behavior itself. It adds useful context by saying the runtime is authoritative and host context is redacted, but it does not explicitly state that the operation is read-only or describe side effects.

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

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

A single sentence with no filler, front-loading the action and resource before qualifiers. Every word earns its place and the structure is immediately scannable.

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 parameterless list tool with an output schema, the description conveys the key behavioral nuance (authoritative, redacted). It could add a hint about what 'host context' includes, but the output schema likely defines the return shape, so the description is largely 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?

There are zero parameters, so the schema already fully covers this dimension. Per the baseline for parameterless tools, a 4 is appropriate; the description needs no parameter-specific details.

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

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

The description uses a specific verb 'List' and identifies the resource 'shells', adding qualifiers 'authoritative runtime' and 'redacted host context' that clarify the tool's scope. It is easily distinguished from siblings like shell_read, shell_write, or shell_exec, which imply different actions.

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 through the verb 'List' – an agent will know to call it for enumeration before operating on a shell – but the description does not explicitly state when to prefer it over siblings or mention any exclusions or alternative 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 of behavioral disclosure. It states persistence but does not disclose that opening a shell creates a stateful resource, starts a process, may need to be closed via shell_close, or how startup_command and env affect the session.

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

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

The description is a single front-loaded sentence with no redundancy, so it is concise. However, it is so terse that it omits important context about lifecycle and usage; it is under-specified rather than efficiently complete.

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?

An output schema exists, so return-value details are likely covered elsewhere, but that does not compensate for missing lifecycle, parameter, and sibling-relationship context. With zero annotations and 0% schema description coverage, the description is inadequate for an agent to use this tool confidently.

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 should compensate for the undocumented cwd, env, and startup_command parameters. It does not: the parameter meanings are left entirely to inference from their names and schema titles.

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

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

The description uses a specific verb ('Open') and resource ('persistent bash command shell'), making the core action clear. The 'persistent' qualifier helps distinguish it from one-off command execution, though it does not explicitly name a sibling alternative.

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

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

No guidance is provided on when to use shell_open versus shell_exec or the other sibling tools. It does not mention that a persistent shell should be opened before shell_read/shell_write, or that shell_exec is for non-persistent commands.

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 of explaining behavior. It discloses that output is incremental and tied to a cursor, but does not state whether reading advances the cursor, whether reads are idempotent, how wait_ms affects blocking, or what happens when output exceeds max_bytes.

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 single sentence is terse and free of filler, and it front-loads the core operation. However, at one sentence with no parameter or behavioral context, it is under-sized relative to the tool's complexity.

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 five parameters, no annotations, and only this description, the definition lacks important operational context—how a cursor is obtained, how incremental advancement works, and how wait_ms/max_bytes shape the read. The presence of an output schema may define the return shape, but it does not fill the input/usage gaps.

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

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

Schema description coverage is 0%, yet the description names none of the five parameters and does not explain cursor, shell_id, exec_id, wait_ms, or max_bytes beyond their raw schema constraints. This leaves the agent without semantic guidance for the 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?

The description uses a specific verb ('Read') and a precise resource ('incremental output from an execution cursor'), clearly distinguishing this from sibling tools like shell_exec, shell_write, or shell_signal. It tells an agent exactly what operation this tool performs.

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 'execution cursor' implies this tool is used after an execution has been started, but there is no explicit 'use this when...' guidance or mention of alternatives. No exclusions or conditions are given, so an agent must infer the 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?

No annotations are available, so the description carries the full burden of behavioral disclosure. It merely says 'Send a portable control intent' and does not explain the effects of interrupt, terminate, or kill, nor the impact on the shell/exec, reversibility, or any side effects. The schema enum hints at behavior, but the description itself adds little.

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 appropriately short with no wasted words, but its brevity sacrifices precision. 'Portable control intent' is unclear terminology, so the single sentence does not earn its place as effectively as it could.

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 only a one-sentence description, the tool lacks the operational context needed to safely signal an execution: what each signal does, whether shell_id and exec_id must reference existing handles, and any preconditions. The schema enum provides structure but not the behavioral semantics, and the output schema does not compensate for missing input and context guidance.

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 the description provides essentially no per-parameter meaning. It does not define shell_id, exec_id, or signal; only 'active execution' loosely suggests exec_id and 'control intent' loosely maps to signal, leaving shell_id 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?

States a clear verb ('Send') and resource ('control intent to the active execution'), and the action is distinct from sibling tools like shell_open, shell_exec, shell_read, and shell_close. However, 'portable control intent' is vague jargon and does not explicitly name the signals that the schema enum lists (interrupt, terminate, kill).

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

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

No guidance is provided about when to use this tool versus siblings such as shell_exec or shell_read, no conditions, prerequisites, or exclusions are mentioned. The agent is left to infer the intended use case from the name and the signal enum.

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 provided, the description bears the full behavioral-disclosure burden, but it only adds an unspecified 'active' qualifier and UTF-8 encoding. It does not disclose whether the write blocks, whether it appends to the process stdin, whether newline termination is required, what happens if the execution is not active, or any buffering semantics.

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 ('Write...') with zero filler; every word earns its place. The imprecision of 'active' is a substance problem, not an organization problem.

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 an output schema exists (relieving the return-value burden), the input side is underserved: 3 required parameters at 0% schema coverage, an undefined lifecycle state ('active'), and no guidance on where this fits among 6 sibling tools. An agent cannot confidently invoke or route to this tool based on the 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%, so the description must compensate, but it only loosely maps 'text' as the UTF-8 content to write. It never explains the distinct roles of shell_id vs exec_id, how they relate (execution belongs to shell), or any constraints on which combinations are valid, so the agent must guess at the IDs' semantics.

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

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

The description states a specific verb ('Write'), a resource ('the active execution'), and a scope ('UTF-8 text'), and the write verb clearly distinguishes it from siblings like shell_read and shell_signal. However, 'active execution' is ambiguous: it reads like a singleton selection, while the schema requires an explicit shell_id and exec_id, leaving the execution-lifecycle meaning unexplained.

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

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

The description gives no when-to-use guidance, prerequisites, or exclusions. Among 6 siblings (shell_open, shell_exec, shell_read, shell_signal, shell_list, shell_close), an agent gets no help deciding that this tool is for sending input after shell_exec, nor why it is preferable to shell_signal for process interaction.

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