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

No annotations are supplied, so the description bears the full behavioral burden. It correctly implies a persistent, side-effecting background process that runs arbitrary commands, but omits lifecycle details: whether the watcher survives restarts, whether it needs cleanup via remove_file_watch, and whether anything is returned to identify the watcher later.

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, well-formed sentence with the core action and trigger condition front-loaded and no filler. Nothing in it could be cut without losing the stated 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?

This tool spawns a long-lived process that executes arbitrary commands, which is meaningful complexity, yet there are no annotations and no output schema. The description leaves the watcher's lifecycle, return value, and relationship to remove_file_watch/list_file_watches unaddressed.

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

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

Schema description coverage is 100%, with each of the four properties documented in the schema itself, so the baseline of 3 applies. The description adds no meaning beyond the schema (e.g., glob semantics, debounce behavior, path 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?

States a specific verb and resource ('Set up a file system watcher') plus its effect ('triggers a command when files change'), so an agent understands exactly what it creates. It does not name its sibling alternatives (remove_file_watch, list_file_watches), so differentiation is only implied by the verb.

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 or when-not-to guidance. The description never says what to do instead if the agent only wants a one-off command run (execute_command) or how this differs from the watch-management siblings.

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 exist, so the description carries the full behavioral burden. It doesn't say whether snapshots persist, whether reusing a name overwrites or errors, whether secret-bearing variables are included, or what the call returns — all material for a capture-and-store operation.

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

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

One tight, front-loaded sentence with no filler — verb and resource appear immediately. It is arguably under-specified rather than padded, but as a structural matter it is efficient.

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 one required parameter, no annotations and no output schema, the description covers enough to invoke the tool correctly. It could say more about persistence and return value, which keeps it below a 5.

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% and the single parameter is fully documented with usage examples, so the schema does the work. The phrase 'with a named label' adds nothing beyond the existing 'name' description; 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: 'capture a snapshot of the current shell environment variables', with the added qualifier 'with a named label'. This distinguishes it in spirit from read-only siblings like get_environment_context and diff_environment, but the description never names those alternatives, so differentiation is left 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?

There is no guidance on when to use this versus get_environment_context, diff_environment, or save_workspace_profile, all of which plausibly overlap with state capture. The only hint of intent lives in the schema example labels ('before-install', 'clean-state'), not in the description.

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

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

No annotations are supplied, so the description carries the full safety-profile burden. It discloses four return levels and mentions suggestions, but does not state whether the command is actually executed, whether analysis is static or live, or whether there are side effects or 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?

Two compact sentences front-load the purpose and result categories. There is no extraneous text.

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 check tool with no output schema, the description gives the key return categories and mentions non-interactive suggestions. It omits definitions of the safety levels and any execution or analysis caveat.

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 is only one parameter and the schema documents it fully at 100% coverage. The description does not add syntax or format details about the command beyond what the schema already provides.

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 ('Check') and resource ('a command') and states the condition being tested (interactive/TTY). It does not explicitly name sibling alternatives, though 'before executing it' implies the relationship to execute_command.

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?

'before executing it' establishes clear timing for when to use the tool. It does not provide exclusions, prerequisites, or named alternatives such as preview_command or suggest_command.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that sessions are removed and that close_tabs also closes terminal tabs, but it does not state whether removal is irreversible, whether active sessions are protected, or what permissions are required.

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 purpose, followed by usage and parameter behavior. It is efficient and readable, though it repeats default values already present in the schema.

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 or annotation coverage, but the description supplies the essential operational context: stale threshold, optional tab closing, and periodic cleanup. It could mention what is returned or whether removals are recoverable, but it is largely sufficient for a two-parameter 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 100%, so both parameters are already fully documented. The description restates the default threshold and the close_tabs behavior, but adds no meaning beyond the schema baseline.

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 clear verb and resource: remove stale terminal sessions that have been inactive. It distinguishes this from general session closing via the 'stale' and 'accumulated tabs' framing, though it does not explicitly name sibling tools like close_session or list_sessions.

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

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

It gives clear usage context: 'Use periodically to clean up accumulated tabs.' This tells the agent when the tool is appropriate, but it does not name alternatives or exclusions, such as when to prefer close_session for individual 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the session closes and that a tab may close, but it omits whether running processes are terminated, whether closure is irreversible, and what happens if the session does not exist.

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 with zero filler, front-loaded with the action and use case. Every sentence contributes 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?

A simple two-parameter tool with rich schema but no annotations or output schema. The description covers the main operation and optional tab behavior, though it could say more about destructive effects and relation to bulk cleanup siblings.

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 both parameters are already fully documented. The description reinforces the close_tab usage but adds no format or edge-case semantics beyond the schema baseline.

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 ('close') and resource ('named terminal session'), and clarifies the optional tab closure. It is clear, but it does not explicitly distinguish itself from sibling cleanup_sessions or list_sessions.

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 says to use it to clean up sessions that are no longer needed, giving clear context. It does not state when-not conditions or mention alternatives such as cleanup_sessions, so it is not 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?

No annotations are provided, so the description carries the full burden. It does disclose the platform ('macOS') and that the target is the system clipboard (a global side effect), but it does not say that existing clipboard contents are overwritten or whether the operation can fail.

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

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

One short sentence that is fully front-loaded with verb and resource, 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 one-parameter tool with a fully documented schema and no output schema, the definition is sufficient to call it, but it omits the overwrite behavior and success/failure semantics that a mutating system-level tool would ideally state.

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 is a single 'text' parameter whose schema description is complete (100% coverage), so the description correctly adds no further parameter detail. 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 ('Copy') and resource ('text to the macOS system clipboard'), and the directionality ('to') makes the contrast with the sibling read_from_clipboard unambiguous. Nothing about the intent is left ambiguous.

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 by the name and description; there is no explicit statement of when to use this versus alternatives or of any preconditions. For such a simple, self-evident tool this is minimally adequate.

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. It does not disclose that deletion is irreversible, whether confirmation is required, what happens if the name does not exist, or the response shape. "Delete" implies mutation but nothing more is conveyed.

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

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

A single, front-loaded sentence with no wasted words. It is appropriately sized for the tool, though brevity here reflects under-specification rather than tight writing.

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

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

For a destructive, non-annotated mutation tool with no output schema, the description omits essential facts: reversibility, error conditions, and any confirmation behavior. The parameter itself is well documented, but the operational picture is incomplete.

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 is one parameter with 100% schema description coverage, so the schema already explains that it is the name of the profile to delete. The description adds no matching or formatting semantics beyond that, which is the expected baseline when schema coverage is complete.

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 (saved SSH connection profile), which is unambiguous. It does not explicitly name or distinguish itself from the adjacent siblings save_ssh_profile or list_ssh_profiles, so it falls short of the top mark.

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 indication of when to use this tool versus save_ssh_profile/list_ssh_profiles, no prerequisites, and no stated behavior for a missing profile. The agent is left to infer usage entirely from the tool 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 behavioral burden and says nothing about the operation being irreversible, whether it fails when the name doesn't exist, or whether deletion affects saved workspace profiles referencing it. Only 'by name' hints at the lookup key.

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

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

One short sentence with the verb and resource front-loaded and zero filler. Nothing extraneous.

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 tool, the purpose is fully conveyed, but as a destructive mutation with no annotations the description should say deletion is permanent and what happens on a missing name. That gap keeps it at minimum-viable 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?

Schema coverage is 100%, and the single 'name' parameter is already documented in the schema, so the schema does the heavy lifting. The description's 'by name' merely restates the identifier, matching the baseline 3.

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 (Delete) and resource (a saved command template), which cleanly separates it from siblings like save_template, list_templates, and run_template. It does not name those siblings explicitly, but the action is unambiguous.

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 run_template or save_template, and no prerequisites or cautions are given. The agent must infer that this is the destructive counterpart to save_template.

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. 'Delete' implies a mutation, but nothing is said about permanence/irreversibility, whether confirmation is needed, or what happens if the name doesn't exist — the key behavioral facts for a destructive operation.

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

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

One short sentence with zero filler, appropriately sized for a single-parameter tool. It is front-loaded but simply too thin to earn a 5.

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 schema fully covers the lone parameter, so the structural side is complete. However, for a destructive tool with no annotations and no output schema, the absence of any note on irreversibility or error behavior leaves a meaningful gap.

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% and there is a single required string parameter already documented as 'Name of the profile to delete'. The description adds no meaning beyond that, so the baseline of 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?

The description uses a specific verb and resource ('Delete a saved workspace profile'), which is unambiguous on its own. It is distinguishable from siblings such as save_workspace_profile and load_workspace_profile by the verb, though the description never names those alternatives explicitly.

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

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

There is no guidance on when to use this rather than list_workspace_profiles or overwriting a profile via save_workspace_profile, and no note that the name must already exist. The agent is given no prerequisites or 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?

With no annotations, the description must carry behavioral disclosure. It indicates that the tool compares snapshots and reports additions/removals/changes, which implies a read-only comparison, but it does not state whether snapshots must already exist, what happens if one is missing, or any permission/auth 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?

The definition is a single efficient sentence with the core action and return categories front-loaded. There is no filler or repetition.

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 two-parameter comparison tool with complete schema coverage, the description is functionally adequate. However, it leaves out practical context such as where snapshot names come from and behavior when a named snapshot does not exist.

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 both parameters are already documented as the 'before' and 'after' snapshot names. The description reinforces that two snapshots are compared but adds no syntax or naming-format guidance 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?

The description gives a specific verb and resource: 'Compare two environment snapshots' and names the categories of result ('additions, removals, and changes'). It is clear what the tool does, though it does not explicitly distinguish itself from related siblings like capture_environment or get_environment_context.

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 says what the tool does but gives no guidance on when to use it versus alternatives, such as when to capture a snapshot first or when to use get_environment_context instead. There are no exclusions or prerequisite conditions.

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 load, and it discloses the single most non-obvious trait: this tool does not emit anything itself, it returns a printf string that a separate execution step must run. It does not cover validation of event_type/payload, error behavior, or the exact shape of the returned string, so it falls short of fully transparent.

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

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

Two sentences, no filler, and the critical constraint (the returned printf must be executed in a pane) is front-loaded right after the purpose statement rather than buried.

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 three-parameter builder with no output schema and no annotations, the essential two-step workflow is explained and the return value is characterized ('the returned printf'). Minor gaps remain: the precise return format (e.g. whether it is bare printf text or wrapped in prose) and how invalid event_type or malformed payload JSON are handled.

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 baseline is 3 — event_type enumerations and the payload default are already documented in the schema. The description adds no per-parameter meaning, such as what each event_type signifies to Warp's UI or the required structure of the payload JSON.

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 pairs a specific verb ('Build a printf invocation') with a specific resource ('OSC 777 warp://cli-agent JSON event into Warp's notification UI'), which is far more precise than the name alone suggests. It also implicitly separates itself from execute_command by framing itself as a builder whose artifact must be executed elsewhere.

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

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

It gives clear operational context: the result must be run inside a Warp pane (e.g. via execute_command) because MCP stdout is the JSON-RPC channel. That tells the agent exactly how to consume the output, though it never states when this tool is preferable to alternatives such as set_notification_preference or send_to_session, nor any exclusion conditions.

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 discloses supported parser targets but says nothing about that this runs arbitrary shell commands, side effects, permission or confirmation requirements, timeouts, or what happens when output doesn't match a parser (only 'auto' is hinted at via the 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?

One front-loaded sentence with zero filler; the parenthetical list is dense but useful. Slightly under-specified rather than over-long.

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

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

No output schema exists, and the description never describes the shape of the 'structured parsed output' or error returns, which is the tool's central promise. For a command-execution tool with no annotations, more behavioral context is needed.

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 all three parameters are already documented, including the parser enum values. The description adds only the notion of parser selection, which the schema already covers, 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+resource ('Execute a command') and adds a distinguishing outcome ('return structured parsed output') plus the supported command families. An agent can separate it from plain execute_command by the parsing behavior, though no sibling is named explicitly.

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

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

The list of supported outputs implies when this tool is the right choice, but there is no explicit statement of when to prefer execute_command, execute_with_streaming, or preview_command instead, and no exclusion guidance.

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, so the description carries the full burden. It usefully discloses that output is captured rather than shown in a tab, but omits whether the call blocks until completion, timeouts, output size/truncation limits, and any risk/permission profile for arbitrary shell execution.

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

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

Two tight sentences with no filler; the core behavior leads and the alternative/scope guidance follows immediately. 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 an unannotated tool that runs arbitrary shell commands with no output schema, the description should cover execution semantics (blocking vs async, timeouts, truncation) and the risk profile. It covers intent and one alternative but leaves these behavioral gaps open.

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% and both parameters are self-describing, so the baseline is 3. The description adds no detail on command syntax, shell used, or how working_directory defaults, so it adds nothing 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+resource ('Executes a terminal command and captures its output') and gives concrete example commands, which is clear. However, the many sibling variants (execute_with_streaming, execute_with_auto_retrieve, execute_pipeline, preview_command) are never differentiated, so an agent still cannot fully disambiguate the execute_* family from this text alone.

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 says this is 'preferred for quick commands' and directs long-running processes to open_terminal_tab, giving a real when-to-use/when-not pair. The gap is that it says nothing about when to prefer execute_with_streaming, execute_with_auto_retrieve, or preview_command, which are closer 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?

No annotations are provided, so the description carries the full burden. It discloses that each step has on_fail behavior, but says nothing about execution environment, side effects, permissions, partial failure outcomes, ordering semantics, or what the tool returns after execution.

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 wasted words. The core behavior and failure-handling modes are stated immediately.

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

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

For an execution tool with no annotations, no output schema, and nested step semantics, the description is too thin. It does not explain execution safety, result reporting, failure semantics per step, or environment behavior that an agent needs before invoking it.

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%, and the schema itself documents the steps array and its on_fail/name/working_directory fields. The description reinforces the conditional-logic concept but adds no syntax or format details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Execute a pipeline of commands') and adds the distinguishing trait of conditional logic with stop/continue/warn failure handling. It is clearly not just a single command, though it does not explicitly name the sibling alternatives it differs from.

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?

Mentioning conditional logic implies this is for multi-step flows where failure behavior matters, but the description never states when to choose this over execute_command, run_template, or preview_command. Usage is only inferable from the pipeline framing.

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 it does disclose that execution blocks and that output is auto-retrieved. It says nothing about timeouts, exit-code or error behavior, output truncation, or side effects of arbitrary command execution. Genuinely useful context, but significant gaps remain for a shell-execution 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?

Two tight sentences with zero waste: the core behavior and the synchronous-output promise come first, then the routing rule against the alternative. Nothing is redundant or buried.

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 two-parameter, fully schema-documented command runner with no output schema, the description covers what it does, how it returns results, and when to prefer it. The missing pieces — timeout behavior and error/exit-code reporting — are modest but real for a command executor.

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% and both parameters (command, working_directory) are documented in the schema itself. The description adds no information about command syntax, shell used, or working-directory defaults, 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?

The description states a specific verb and behavior: executes a command, waits for it, and returns its output. The blocking/auto-retrieve semantic is a genuine differentiator. However, it does not distinguish itself from close siblings like execute_command, execute_with_streaming, or execute_and_parse, which an agent would also plausibly reach for.

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

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

It gives a clear selection rule — 'preferred for quick commands that don't need a visible terminal tab' — and explicitly names open_terminal_tab as the alternative for long-running processes. It stops short of addressing the arguably more confusable siblings (execute_command, execute_with_streaming), leaving that comparison to inference.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers little: it says output streams in real time but not whether the call blocks until completion, what happens to partial output when max_duration is hit, whether the command runs in a shell, or what safety/permission posture applies to arbitrary command execution. Only the streaming trait is disclosed.

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 core capability first and the use case second; nothing is wasted. It is, however, terse to the point of under-specification for a tool that runs arbitrary commands.

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?

Four parameters, no annotations, and no output schema, yet the description says nothing about what comes back — output format, whether exit status/errors are included, or how streamed chunks are surfaced. For a command-execution tool with zero structured support for behavior or returns, this leaves material 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 100%, including defaults for max_duration and update_interval, so the schema already does the work. The description adds nothing about parameter interplay (e.g., how update_interval interacts with streaming granularity), so the 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 ('Execute a command') plus the distinguishing capability ('real-time output streaming'). It implicitly separates itself from execute_command and get_command_output via the streaming qualifier, but never names the sibling it differs from, 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?

'ideal for long-running builds' hints at the usage context, but there are no explicit when-not conditions and no alternatives named despite many siblings (execute_command, execute_with_auto_retrieve, get_command_output) that an agent must choose between. Usage is implied rather than directed.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the prerequisite UUID source and an important invalid-input case, but does not explain what focusing does to the active pane, what happens when the UUID is not found, or whether Warp must be running.

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

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

Three sentences, front-loaded with the action, followed by valid UUID sourcing and the invalid alternative. Every sentence 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 one-parameter focus tool with no output schema and no annotations, the description covers the action, valid input source, and a key invalid-input warning. It could be more complete by stating the effect on pane focus or failure behavior, but it is sufficient to invoke correctly.

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 specifying that the UUID must be Warp-recognised and typically comes from the shell shim, while locally-minted UUIDs from open_terminal_tab are invalid.

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 and resource: 'Focus an existing Warp pane by its session UUID.' It also explicitly distinguishes the valid UUID source from the locally-minted UUIDs returned by open_terminal_tab, so an agent can tell this apart from related session tools.

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

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

It gives clear usage conditions: the UUID must be one Warp itself recognises, typically from the shell shim's OSC 777 event, and locally-minted UUIDs from open_terminal_tab are not valid. It does not explicitly contrast this with siblings like send_to_session, but the exclusion of open_terminal_tab UUIDs is strong guidance.

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: not whether retrieval is idempotent or consumes the output, not what happens for an unknown or expired command_id, and not whether output is truncated. Only the read-oriented nature is implied by 'Retrieve'.

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. It is not padded, though it is terse enough that the missing detail reads as under-specification rather than deliberate economy.

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-optional-parameter read tool this is close to adequate, but with no annotations and no output schema the description should say what is returned (raw text vs structured, truncation) and how errors surface for an invalid or 'last' with no history. Those gaps keep it from 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% and the command_id description already documents the 'last' sentinel, so the description adds no parameter meaning beyond the schema. Baseline 3 is appropriate when the schema does all the work.

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 (Retrieve) and resource (output of a previously executed command), which clearly places it in the post-execution retrieval lane rather than the execute_* family. It stops short of naming a sibling such as execute_with_auto_retrieve or list_recent_commands, so the boundary is inferred rather than stated.

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

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

No guidance on when to call this instead of execute_with_auto_retrieve, execute_with_streaming, or list_recent_commands. Nothing says whether prior output expires, whether retrieval is required after a plain execute_command, or what happens if no command has run.

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 must carry the behavioral burden. It usefully discloses what the current context includes (git branch, venv, node version, docker status, working directory), but does not explicitly state that it is read-only, whether it can be slow when checking docker, or what the return structure looks like.

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 definition is a single front-loaded sentence that states the action and lists the relevant context fields without filler. Every element 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?

With one optional parameter, no output schema, and no annotations, the description does a good job listing the returned context components. It could be more complete by stating the return shape or explicitly confirming the read-only nature, but the core information needed to call the tool is 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 100%, and the single optional parameter 'working_directory' is fully documented in the schema as defaulting to the current directory. The description adds no parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Get current terminal environment context') and enumerates the exact context fields returned. It is clear what the tool does, though it does not explicitly differentiate itself from nearby tools like capture_environment or diff_environment.

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 implies usage by saying it retrieves current context, but gives no explicit guidance on when to use this tool versus capture_environment, diff_environment, or other environment-related siblings. There are no exclusions, prerequisites, or alternative-selection cues.

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 exist, so the description carries the full burden. It implies a safe read via 'List' and filters to 'active' watchers, which is useful. However, it says nothing about the return shape (what a watcher record contains), ordering, or whether inactive/removed watches could ever appear, leaving gaps for a no-annotation tool.

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

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

A single front-loaded sentence with no wasted words. Appropriately sized for a trivial listing tool, though it could be slightly more informative without becoming verbose.

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

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

For a 0-param, no-annotation, no-output-schema tool, the description is nearly complete but omits what a returned watcher looks like (path, ID, events). An agent can call it correctly but cannot anticipate the output structure from 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?

The tool takes zero parameters (schema coverage 100%), so there is no parameter semantics to explain; the baseline for a 0-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?

States a specific verb ('List') and resource ('active file system watchers'), which clearly distinguishes it from the sibling mutation tools add_file_watch and remove_file_watch. It stops short of naming those alternatives explicitly, but the read-only listing purpose is unambiguous.

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 guidance on when to call this versus add_file_watch/remove_file_watch, nor any mention of prerequisites. The word 'active' hints at scope (excluding inactive watches), but that is left implicit rather than stated as a usage 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only that history is read and what fields appear (status, duration, exit codes); it says nothing about ordering (most-recent-first?), whether the list is scoped to the current session/workspace, retention depth of history, or read-only safety.

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; every clause (verb, scope, returned fields) 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?

With three fully documented optional parameters and no output schema, the description covers the essentials and helpfully names the returned fields. It still leaves meaningful gaps for a history tool: sort order, scope of history, and how 'recent' is bounded.

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 all three parameters (limit with its 1-50/default-10 range, search, status) are already documented. The description adds nothing beyond echoing the returned fields, and notably does not clarify that 'limit' is typed as a string.

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 ('recent commands from history') plus the returned fields, which clearly separates it from execution siblings like execute_command or get_command_output. It stops short of naming a sibling explicitly, but the resource is unambiguous.

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?

'From history' implies this retrieves already-executed commands rather than running new ones, which is an implicit disambiguation against execute_command. However, there is no explicit when-to-use guidance, no mention of when to prefer get_command_output for a single command's full output, and no stated exclusions.

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 must carry behavioral disclosure; it implies a safe read via 'List' and states the scope ('all active'), which is useful. However, it does not describe what a session record contains (IDs, names, state), which matters because those identifiers are needed to call send_to_session, and there is no output schema to fill the gap.

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, each earning its place: what it does, when to call it, and what to do next. The core purpose is front-loaded.

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 the description covers purpose and workflow routing well. The only real gap is the absence of any hint about the returned session fields, which matters given no output schema and a downstream dependency on session identifiers.

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 for the description to disambiguate; baseline 4 applies. It correctly implies no filtering or targeting is required.

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 all active terminal sessions') with a clear scope qualifier ('active'). It is immediately distinguishable from siblings like open_terminal_tab and send_to_session, which are named or implied.

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 prescribes when to call it ('Check this before opening new tabs to avoid creating duplicates') and names the alternative workflow ('Reuse existing sessions with send_to_session whenever possible'). Both the trigger and the follow-up action are given.

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 behavioral burden; "List" implies a read-only operation and "all saved" defines scope. However, it does not disclose whether sensitive SSH details are returned, whether credentials are redacted, or what permissions are required.

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 definition is a single front-loaded sentence with no wasted wording. It is appropriately sized for a zero-parameter list operation.

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 description is sufficient to understand the basic operation, but with no output schema it does not describe the returned profile fields or whether secrets are included. For a simple list tool this 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify beyond the empty 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?

The description states a specific verb and resource: "List all saved SSH connection profiles." It clearly separates this read-only profile enumeration from siblings such as save_ssh_profile, delete_ssh_profile, and ssh_execute.

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

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

It gives no explicit guidance on when to use this tool versus alternatives like list_workspace_profiles or ssh_execute. The usage is only implied by the name and the word "saved."

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 behavioral disclosure. Beyond the word 'List' implying a read operation, it says nothing about ordering, scope (global vs workspace), or what is returned.

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 wasted words, and the verb/resource are front-loaded. It is appropriately sized for a zero-parameter tool, though it could add one clarifying phrase about scope.

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 zero-parameter listing tool, the description is minimally adequate. However, without annotations or an output schema, it leaves open whether templates are listed globally or per workspace and what format they are returned in.

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 is already complete and there is no parameter semantics to explain. The description does not need to compensate for any schema 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 uses a specific verb ('List') and resource ('all saved command templates'), making the operation clear. It does not distinguish itself from nearby siblings such as list_recent_commands or run_template, but the core purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives. Siblings like list_recent_commands and save_template create potential confusion that the description never addresses.

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 disclosure burden. "List all saved" weakly implies a read-only, unfiltered enumeration, but it says nothing about ordering, whether empty results are possible, or what a "profile" contains — significant gaps for a zero-annotation tool.

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

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

A single front-loaded sentence with no filler. It is arguably too terse, but nothing in it 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?

With no output schema, the description should hint at the shape of returned profile objects or at least whether names/IDs are included. For a trivial zero-param list tool this is a minor gap, but it is still a gap.

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 for the description to clarify; baseline 4 applies. The schema is empty and fully self-consistent with the description.

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

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

The description states a specific verb and resource ("List all saved workspace profiles"), so the agent knows exactly what it returns. It does not differentiate itself from sibling lifecycle tools like save_workspace_profile, load_workspace_profile, or delete_workspace_profile, though the names make the distinction fairly obvious.

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

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

There is no guidance on when to call this versus load_workspace_profile or save_workspace_profile, and no stated preconditions. The agent must infer that this is a discovery step before loading a profile.

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 must carry the full behavioral burden. It does not explain what state is restored, whether it overwrites the current workspace context, what happens if the named profile does not exist, or whether the operation is reversible.

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 wasted words. It is efficient, though its brevity contributes to the behavioral gaps noted elsewhere.

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 complete schema coverage and no output schema, the description identifies the action and likely purpose. However, because there are no annotations and the tool appears to alter workspace state, the description is incomplete regarding side effects and failure behavior.

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 is one parameter with 100% schema description coverage, so the schema already defines 'name' clearly. The description adds no extra parameter semantics beyond the schema, which is acceptable given the complete schema but not enriching.

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 and resource ('Load a saved workspace profile') and adds an outcome ('restore project context'). It is clear but does not explicitly differentiate itself from siblings such as list_workspace_profiles, save_workspace_profile, or delete_workspace_profile.

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 'restore project context' implies when the tool is useful, but there is no explicit guidance on when to choose this over listing profiles or creating a new workspace. 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 behavioral burden and does disclose the important side effect: this creates a *visible* tab, and an existing session should be reused rather than duplicated. It does not address what happens with duplicate names, whether the call blocks until the tab is ready, or how the tab is cleaned up (left to the sibling close_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?

Three sentences, front-loaded with the action and the hard constraint ('ONLY use for long-running commands'), then alternatives. No redundant restatement of the title or schema.

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 low-complexity, three-parameter tool with a fully documented schema and no output schema, the description covers purpose, constraints, and alternatives well. The only gap is what the agent gets back (session name/id or a handle to pass to send_to_session), which would help close the loop with the reuse sibling.

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 all three parameters (name, terminal, working_directory) are already documented in the input schema. The description only implies the 'name' parameter via 'named terminal tab' and adds no format, uniqueness, or default-terminal detail beyond the schema, so the 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?

The description gives a specific verb and resource ('Open a new named terminal tab') and immediately differentiates this tool from the many execute_* siblings by scoping it to long-running, visible-tab work. An agent can distinguish it from execute_command and send_to_session without consulting 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?

It states explicit when-to-use criteria (builds, installs, servers, cloning repos), explicit when-not (quick commands), and names two concrete alternatives (execute_command, execute_with_auto_retrieve) plus a reuse path (send_to_session). This is about as complete as routing guidance gets.

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

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

With no annotations, the description carries the full burden; it does disclose the single most important behavioral trait (no execution side effects). However, it never explains what a 'preview' actually contains (shell expansion, validation, risk analysis) or whether it touches the environment, which is critical for a command tool.

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

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

A single tight sentence with the key safety qualifier front-loaded after the verb. Efficient, though arguably too terse given the ambiguity of 'preview'.

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 annotations and no output schema, so the description must define the return value and side-effect profile; instead it leaves ambiguous whether preview parses, expands, or validates the command. An agent cannot predict the result it will get.

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?

Only one parameter and schema coverage is 100%, so the schema already documents 'command' fully. The description adds nothing about format, quoting, or multi-command input; 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 ('Preview') and resource ('a command') and adds the distinguishing qualifier 'without executing it', which separates it from the many execute_* siblings. It stops short of naming a sibling explicitly.

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

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

The phrase 'without executing it' implies a pre-flight/dry-run use case versus execute_command, but usage is only implied; there is no explicit when-to-use, when-not-to-use, or named alternative.

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. 'Read' implies a non-mutating operation and the macOS scoping hints at platform requirements, but there is no disclosure of permission/accessibility requirements, behavior in headless or SSH contexts, or what happens when the clipboard is empty or holds non-text data.

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; every word earns its place and the resource and platform are stated up front.

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 trivial zero-param read, the description covers what it does but not what comes back. With no output schema, the agent cannot tell whether the result is plain text, an image, or an empty/null value, nor how failure is signaled.

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?

With zero parameters and 100% schema coverage there is nothing to document, so the baseline of 4 applies. The description adds no parameter-level detail because none is needed.

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 (read) plus the exact resource (macOS system clipboard), which is unambiguous. It does not name the sibling copy_to_clipboard as its inverse, but the pairing is self-evident from the names.

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 infers it should call this when it needs clipboard contents and use copy_to_clipboard to write. There is no explicit when-to-use statement, no exclusion, and no mention of 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?

No annotations exist, so the description carries the full behavioral burden. It does not state whether removal is immediate/irreversible, whether it errors on an unknown or already-removed watcher_id, or whether in-flight events are dropped — all material facts for a destructive operation.

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 or redundancy. It is lean to the point of under-specification, but nothing in it 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 destructive tool with zero annotations and no output schema, the description omits irreversibility, error behavior, and how to obtain a valid watcher_id. An agent has to guess at the failure modes before invoking it.

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% and the single parameter is documented as 'ID of the watcher to remove'. The description adds no format, source, or validation detail beyond that, so the 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 ('Remove') and resource ('an active file system watcher'), which cleanly distinguishes it from add_file_watch and list_file_watches by name. It stops short of explicit sibling routing, but the operation itself is unambiguous.

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 deletion verb, but the description never says when to use this versus list_file_watches to discover a valid ID, nor what happens if the watcher is already gone. No exclusion or prerequisite guidance is given.

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 implies a side-effecting execution but never states whether the command's output is returned inline or must be fetched via get_command_output, what happens if the template name is unknown, or whether missing variables error out. These are the traits an agent needs before invoking it.

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 waste. It is efficiently sized, though its brevity is part of why behavioral and usage context are absent.

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 command-execution tool with no annotations and no output schema, the description omits return behavior, error conditions, and how the result relates to get_command_output. It is not complete enough for an agent to call this confidently in a side-effecting 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?

Schema description coverage is 100%, so both parameters are already documented in the schema, setting the baseline at 3. The phrase 'with variable substitution' adds a little meaning about how the variables object is applied, but does not specify format or substitution syntax 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: 'Execute a saved command template', plus the key mechanic of variable substitution. However, it does not differentiate from the sibling execute_command, leaving the agent to guess which one reads a stored template versus running a raw command.

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 or when-not-to-use guidance, and no alternatives named despite many overlapping siblings (execute_command, preview_command, list_templates, save_template). The agent must infer that a template must already be saved and that list_templates is how to find 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 behavioral burden and does not meet it: it never says whether saving a profile with an existing name overwrites or errors, where the profile is persisted, or whether the private key path is validated or the key itself stored. For a mutation tool with zero annotation coverage, this is a meaningful gap.

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 the core action front-loaded and no filler. It is efficient, though its brevity is part of what leaves the behavioral questions unanswered.

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 five-parameter mutation tool with no annotations and no output schema, the description should cover collision behavior, persistence scope, and typical follow-up (ssh_execute). None of that is present, so an agent cannot predict what a successful or failed save looks like.

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 all five parameters (name, host, username, port, identity_file) are documented in the schema, establishing the baseline of 3. The description adds nothing about defaults, accepted formats, or the significance of optional fields such as identity_file.

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

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

The description gives a specific verb and resource ("Save an SSH connection profile") plus a purpose ("quick reuse"), which is clearly distinct from ssh_execute and list_ssh_profiles. It does not explicitly name those siblings or state the boundary (persisting a profile vs. running a connection), 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?

There is no statement of when to call this instead of ssh_execute, save_workspace_profile, or list_ssh_profiles, and no prerequisites or preconditions. An agent must infer from the name alone that this is the persistence step before running ssh_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 provided, so the description carries the full behavioral burden. It does not explain what happens if the template name already exists, whether the save overwrites or fails, where templates are persisted, or what the tool returns.

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 wasted words. It states the action, the resource, and the purpose immediately.

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

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

For a low-complexity save operation with fully documented parameters and no output schema, the core purpose is covered. However, with no annotations, it leaves important mutation behavior such as duplicate-name handling and persistence scope unstated.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description adds only the general idea that templates contain variables, while the schema supplies the concrete {{variable}} syntax and field meanings.

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 and resource: 'Save a command template with variables for reuse.' It clearly distinguishes saving from sibling actions like run_template, list_templates, and preview_command, though it does not name 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?

The phrase 'for reuse' implies when this tool is useful, but there is no explicit guidance on when to choose it over alternatives such as run_template or list_templates, nor any exclusions or 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 it does disclose the notable side effect: an optional file written to ~/.warp/launch_configurations/ that surfaces the profile in Warp's launch UI. It does not say where profiles themselves are persisted, whether saving a name that already exists overwrites or errors, or what is returned.

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 core action and followed by the optional side effect. No filler, though the second sentence is somewhat compressed and would read better split.

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

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

No output schema and no annotations, so the description must cover behavior: it covers the Warp config write but leaves open profile storage location, overwrite semantics, and return value. Adequate for the happy path but incomplete for an agent needing to know the consequences of reusing a name.

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 baseline is 3. The parenthetical list of captured fields mirrors the schema properties rather than adding semantics, and the env-var exclusion note for the Warp config is already stated 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?

Specific verb+resource: 'Save current project context as a named workspace profile', with the captured fields enumerated in parentheses. It is distinguishable from load/delete_workspace_profile by the verb, though it never contrasts itself with the similar-sounding save_template or save_ssh_profile siblings.

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 ('save current project context', optional Warp launch config) but there is no explicit when-to-use guidance, no mention of when to prefer save_template instead, and no stated preconditions such as an active project context.

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

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

With no annotations, the description carries the burden and it does disclose scope (four subsystems checked), which implies a read-only diagnostic. However it never confirms it is non-mutating, says nothing about latency or whether it touches live sessions, and gives no sense of what a failure result looks like.

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

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

One sentence, front-loaded with the action and enumerating the checks. Nothing is padded and nothing important is buried.

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 (zero params, no nested objects), and the description covers what is checked. But with no output schema and no annotations, an agent still can't tell what the result contains or how to act on it, which is the main remaining gap.

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 parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies no input is needed.

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 ('Run health check') plus the resources inspected: configuration, database, terminal, and recent error rates. It's a diagnostic tool clearly distinct from the command-execution and workspace siblings, though it doesn't name a sibling it contrasts with.

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

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

No guidance on when to invoke this versus siblings like get_environment_context or wave_helper_status, both of which also sound diagnostic. There is no statement of prerequisites or when not to use it.

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 exist, so the description carries the full burden. It usefully discloses that the tab is reused (no new resource created) and that a session must pre-exist, but says nothing about what happens if the session name is unknown, whether the call is blocking, or how output is obtained (a sibling get_command_output exists).

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, then the preference rule, then the prerequisite. No filler; every sentence changes agent 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?

A simple two-parameter tool with a fully documented schema and no output schema; the description covers selection and prerequisite context adequately. The main residual gap is output retrieval guidance for a command-sending 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 100%, so both parameters are already documented in the schema; baseline 3 applies. The description adds only that session_name must refer to an existing named session, with no details on name matching or command syntax.

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+resource: send a command to an existing named terminal session, and clarifies it reuses the session's tab rather than creating one. This distinguishes it from open_terminal_tab, though other execution siblings (execute_command, execute_with_streaming, wave_run_in_block) are never named as contrasts.

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?

Explicit positive guidance ('Always prefer this over opening a new tab when a relevant session already exists') plus a concrete prerequisite step ('Use list_sessions first to check for available sessions'). The when-to-use condition and the alternative are both spelled out.

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

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

With no annotations, the description carries the full behavioral burden and falls short. 'Toggle' is ambiguous for a tool that accepts explicit boolean and numeric values, leaving open whether it flips current state or sets absolute values. It also omits whether partial updates are allowed, whether settings persist across sessions, and any permission or macOS-version 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?

A single front-loaded sentence with no filler, and the scoping qualifier 'for command completion alerts' appears early. It is efficient, though so terse that the brevity reflects under-specification rather than disciplined economy.

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?

Five optional parameters, no annotations, and no output schema mean the description must do more work than one sentence allows. It says nothing about partial-update semantics, defaults, persistence scope, or the effect of calling it with an empty argument object, all of which an agent needs before invoking it.

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 all five parameters are already documented in the schema, establishing a baseline of 3. The description only adds the framing that these settings govern completion alerts, which mildly clarifies the meaning of 'enabled' and 'sound' but adds no syntax, units, or default information 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?

The description states a specific verb and resource: toggling macOS notification preferences scoped to command completion alerts. That is clear enough to distinguish it from unrelated siblings like wave_set_setting or execute_command. It does not explicitly contrast itself with any sibling, and the word 'toggle' is a slightly loose fit for a 5-parameter setter.

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

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

There is no guidance on when to call this versus alternatives such as wave_set_setting. Nothing states whether it applies globally or per-session, whether omitting parameters preserves existing values, or what defaults apply. The agent must infer all invocation conditions.

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 meaningful behavior: the shim is opt-in via helper/install-shim.sh, streams preexec/command_finished events over a per-uid Unix socket, and is an observability surface in v6.0 rather than an execution path. It does not explicitly state read-only safety, permissions, or behavior when the shim is not installed, but "Report the status" strongly implies a non-mutating diagnostic operation.

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 returned status fields and then supplies the operational context needed to interpret them. The final sentence about deferred auto-routing is slightly ancillary but earns its place by preventing an agent from assuming this tool changes execute_command 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?

With zero parameters and no output schema, the description usefully lists the status information the caller receives and explains how the shim becomes active. It could be more complete by describing behavior when the shim is not installed or not listening, but it provides enough context for an agent to invoke the diagnostic correctly.

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 there are no parameter semantics to explain and the baseline is 4. The schema coverage is 100% and the description correctly does not invent parameter details that do not exist.

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 and resource ("Report the status of the optional shell shim") and enumerates the status fields returned: socket path, listening state, event count, and recent events. It also distinguishes this observability tool from execute_command by noting that shim-based auto-routing is deferred to v6.0.x.

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

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

The description explains that the shim is opt-in and active inside a Warp pane, which gives useful context for when the status is meaningful. However, it never explicitly states when an agent should call this tool versus alternatives such as self_check, nor does it describe when the tool would be unhelpful or how to react if the shim is inactive.

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

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

No annotations are supplied, so the description carries the full burden, and it does disclose one important behavioral constraint: key-based authentication only, which rules out password or agent prompting. It says nothing about whether the command is non-interactive, how output or exit codes are surfaced, or what happens on timeout/connection failure — significant gaps for a remote execution tool.

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

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

A single tight sentence with no filler, and the core action is front-loaded. Its brevity is efficient rather than padded, though the parentheses carry the only differentiating detail at the tail.

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 7 parameters, no annotations, and no output schema, an agent needs more than this — notably how results and failures are returned, whether profile overrides host/username, and whether execution is blocking for the duration of the timeout. The description leaves the entire behavioral surface of a remote execution tool undocumented.

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 defaults for port, timeout, identity_file, and the profile alternative are already documented in the schema. The description adds only the auth-mode constraint that explains why identity_file matters, which is a marginal but real addition over 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: execute a command on a remote host over SSH. An agent can distinguish it from the SSH-profile management siblings (save_ssh_profile, list_ssh_profiles) and from local execution tools. It does not explicitly differentiate it from generic siblings like execute_command, so it stops short of a 5.

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

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

There is no guidance on when to choose this over execute_command, run_template, or wave_run_in_block, which all appear in the sibling list and could plausibly run commands. The only usage constraint given is the authentication mode, not the selection criteria.

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. 'Suggests' implies nothing is executed, which is a useful signal, but it doesn't state whether the result is a command string, whether it validates the command, whether working_directory changes output semantics, or any side effects. That is thin for a tool whose safety profile is undeclared.

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 padding. It is efficient but borders on under-specified rather than tight—there is room for one more clause on output or usage without bloat.

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 annotations and no output schema, so the description should clarify what a 'suggestion' looks like and how it differs from preview_command's output. With only one sentence, an agent cannot tell whether the response is a command string, a list of alternatives, or an explanation.

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 both query and working_directory are already documented, including the context-aware git/Swift/Node behavior. The description adds nothing beyond echoing the query parameter, so the 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?

Clear verb ('Suggests') and resource ('a terminal command') plus the input basis ('based on the user's request'), so the agent knows this is a suggestion generator rather than an executor. However, it never distinguishes itself from close siblings like preview_command, execute_command, or check_interactive, which an agent must disambiguate by itself.

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

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

No statement of when to use this instead of execute_command or preview_command, and no prerequisites or exclusions. The agent is left to infer that 'suggest' is the advisory, non-executing path from the single verb alone.

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