shell-use

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

No annotations are present, so the description carries the full burden of behavioral disclosure. 'Captures current terminal screen text' implies a read operation but does not state side effects, whether scrollback is consumed, or whether terminal state is altered. This lack of detail leaves the agent uncertain about the tool's safety profile.

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 sentence that immediately conveys the tool's core purpose. It contains no filler, repetition, or irrelevant details, making it optimally concise while still informative at a high level.

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 presence of an output schema reduces the need to explain return values, but the tool has two parameters and operates in a terminal context with sibling tools like scroll. The description does not explain how 'session' and 'scroll_back' affect behavior, nor whether capture requires a specific mode. With 0% schema coverage, this is insufficient for effective 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%, and the description does not mention either parameter. The required 'session' and optional 'scroll_back' remain unexplained, providing no semantic value beyond the bare names and types in the schema. The description fails to compensate for the lack of 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?

The description clearly states the action ('captures') and the resource ('current terminal screen text'), providing a specific verb+resource definition. It doesn't explicitly mention sibling tools, but the action is distinct enough that no alternative is needed. Slight ambiguity in what 'capture' means (return text vs. save) prevents 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?

No guidance is provided on when to use capture versus scrolling or sending keys. The description does not specify whether a session must be active, whether capture works in scroll mode, or any prerequisites. It gives no context for selecting this tool over alternatives.

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 carries the full burden of explaining behavior. It accurately discloses the state transition without hidden side effects. However, it does not mention prerequisites (e.g., whether session must be in copy-mode) or error behavior, but for this simple tool the core behavior is 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?

The description is a single clear sentence with no unnecessary words or repetition. It front-loads the action and is immediately understandable.

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 state-transition tool with an output schema, the description covers the core action but lacks information about the required 'session' parameter and any prerequisite conditions. This makes it minimally viable but not fully complete for an agent to invoke correctly without additional context.

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

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

The input schema has one required parameter 'session' with 0% schema description coverage, and the description provides no explanation of what this parameter represents or how to determine its value. This is a significant gap, as the description adds no meaning beyond the parameter's name and 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 clearly states a specific action ('Exits tmux copy-mode') and the resulting state ('returns to normal mode'). This distinguishes it from sibling tools like scroll or capture, 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 implies usage when the user is in tmux copy-mode and wants to return to normal mode, but it does not explicitly state when to use this tool versus alternatives like 'scroll'. There are no exclusions or alternative recommendations, so guidance is only implicit.

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?

There are no annotations provided, so the description carries the full burden. It indicates a read-only operation by 'Returns list', but doesn't disclose additional traits such as whether the list is a snapshot or includes all session states.

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 sentence with no extraneous words. It is front-loaded and immediately conveys the tool's purpose.

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

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

For a zero-parameter, read-only tool with an output schema, the description sufficiently conveys the tool's purpose and invocation. No additional context is necessary.

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 has zero parameters, so the schema fully covers parameter space. The description adds no parameter details, but none are needed given the baseline of 4 for zero-parameter tools.

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 'Returns list' and clearly identifies the resource 'available tmux sessions'. This clearly distinguishes it from sibling tools that send input or capture output.

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 does not explicitly state when to use this tool versus alternatives, though the purpose is unambiguous. Usage is implied rather than stated, so the agent must infer when to list sessions.

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 carries the full burden of behavioral disclosure. It reveals only the default half-page behavior, but does not clarify whether the operation is view-only, what the effect on the session is, or any side effects. This is minimal for a tool without annotation support.

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, efficient sentence with no filler. Every word contributes to the meaning, making it highly concise and 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?

The tool has an output schema and relatively simple parameters, so the description need not cover return values. However, the lack of usage guidance and minimal behavioral detail leaves some contextual gaps for an AI agent, especially given no annotations.

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 description adds meaning to the 'amount' parameter by noting 'half-pages by default', which helps interpret the default value of 1. However, it does not explain 'session' or 'direction' explicitly, and with 0% schema coverage, it only partially compensates for the missing parameter documentation.

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

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

The description uses a specific verb ('navigates') and a specific resource ('scrollback buffer'), clearly distinguishing it from sibling tools like send_keys or capture. The parenthetical 'half-pages by default' adds useful scope.

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 when to use the tool (when you need to navigate the scrollback buffer) but provides no explicit guidance on when not to use it or what alternatives exist. It does not mention relationships to siblings like exit_scroll_mode.

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 mentions support for tmux key notation but does not disclose side effects, whether it requires an active session, or any error conditions. For a mutation-like tool, this is insufficient.

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 extremely concise, two sentences with no filler. It front-loads the primary action and then adds the key notation detail. Every word 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?

The tool is simple, but the description is minimal. It lacks context about the session parameter, usage in workflows, and any behavioral nuances. While an output schema exists, the description alone does not adequately complete the picture for an agent deciding whether and how to invoke the 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 clarify parameters. It explains the 'keys' parameter via tmux notation, but entirely omits the 'session' parameter, leaving it undefined. The description adds partial meaning to one parameter but fails to cover the second.

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 it sends key input and supports tmux key notation, which clearly defines the action and resource. It differentiates somewhat from siblings like send_text by emphasizing key notation, but it does not explicitly contrast with send_text.

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 this tool versus alternatives like send_text. The description implies usage for key input operations but does not state exclusions or alternative scenarios, leaving the agent to infer 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 to rely on, the description carries the transparency burden and does well: it explains literal text handling, multiline support with \n and \t, and the Enter behavior. It does not mention return values or error conditions, but an output schema exists, so those are covered elsewhere.

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 well-structured and concise: a single-sentence definition, followed by parameter-specific guidance, and two illustrative examples. Every line serves a purpose without redundant elaboration.

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 relatively simple 3-parameter tool with an output schema, the description covers the essential behavior, parameter semantics, and practical examples. It lacks details about session validation or failure modes, but these are not necessary for basic selection and 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 description coverage is 0%, so the description must compensate. It does for two of three parameters: text (literal multiline with escapes) and enter (boolean controlling Enter key press). The session parameter is not explicitly described, though its usage is shown in examples; given the low schema coverage, this is a minor 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 opens with a specific verb+resource: 'Sends literal text via tmux buffer.' This clearly states the tool's core purpose and distinguishes it from sibling tools like send_keys by emphasizing 'literal text' rather than key sequences. The examples further reinforce what the tool does.

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 explicit guidance for parameter usage: 'Use enter=True for shell commands' and 'Use enter=False (default) for editors.' This provides clear context for when to use which setting, though it does not explicitly compare against sibling tools like send_keys or list_sessions, so it stops short of a full when/when-not comparison.

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