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 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 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 exist, so the description carries the full burden. It discloses default silent execution and the visibility toggle, but says nothing about the safety profile of running arbitrary shell commands, permissions, timeouts, exit-code/error behavior, or output size limits. For a potentially destructive command-execution tool that is a significant omission.

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?

Short and front-loaded: the core action comes first, then the visibility guidance. The parenthetical '(no visible block)' and the '5 consecutive commands' instruction are slightly awkward phrasing but do not pad the 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?

Covers the core action and the one non-obvious parameter, which is adequate for a 3-parameter tool. But with no annotations and no output schema, the description should have explained what 'captures its output' yields (exit codes, truncation, failure reporting) for an agent to call this reliably.

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 baseline is 3. The description adds genuine value beyond the schema for show_in_wave by naming the scenarios that warrant a visible block and the rule for consecutive calls. working_directory is left to the schema, which is acceptable given full coverage.

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 ('Executes a terminal command and captures its output'), which is unambiguous on its own. However, it never distinguishes itself from close siblings like execute_pipeline, execute_with_streaming, execute_and_parse, ssh_execute, or wave_run_in_block, so an agent cannot tell from the description which execution tool applies.

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

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

The description does give real usage guidance, but only for the show_in_wave parameter (use it for builds/installs/multi-step processes; leave unset otherwise). It offers no guidance on when to choose this tool over the many alternative execution siblings, which is the harder selection decision.

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?

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?

Even without annotations, the description makes the read-only, lightweight nature clear through "cheap peek" and the stated return values. It discloses scope across the global inbox and every registered project inbox, though it does not explicitly state that no side effects occur.

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

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

Front-loads the core purpose, then states the return values, then gives the usage rule. Three short sentences with no filler.

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

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

For a zero-parameter, no-output-schema tool, the description supplies the key return information: total unread count, age of oldest message, and per-project breakdown. That is enough for an agent to decide whether to call it and what to expect.

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 document. The schema is empty and the description correctly focuses on behavior and return values rather than invented arguments.

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 resource and action: a cheap peek across the global inbox and all registered project inboxes. It also explicitly distinguishes this from read_user_inbox by saying to call it when you only need to know whether anything is waiting.

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?

Provides explicit routing guidance: call this before read_user_inbox if you only want to know whether anything is waiting. That clearly frames the alternative and the condition under which this tool is preferred.

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 burden; it does contribute that results span all inboxes and are sorted most-recent-first, which is real behavioral detail. However, it omits read-only confirmation, whether archived includes threads/replies, and any result-shape or paging behavior beyond the limit param.

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

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

Two short sentences with zero filler; scope is front-loaded followed by the ordering guarantee. Nothing redundant.

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 zero-required-parameter browse tool with full schema coverage and no output schema needs little more than this. The main omission is differentiation from read_user_inbox and a hint about what a returned message contains.

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 limit, search, and project are already fully documented in the schema with defaults and matching rules. The description adds only the sort order, which is not tied to any parameter, 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 ('Browse') and resource ('archived messages') with explicit scope ('all inboxes: global + every registered project') and ordering. It does not distinguish itself from the sibling read_user_inbox, which appears to overlap in purpose, so an agent cannot fully disambiguate from the description 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?

Says nothing about when to prefer this over read_user_inbox, inbox_count, or read_my_replies. The 'archived / across all inboxes' wording hints at a broad historical view, but no conditions or exclusions are stated.

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

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

No annotations 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that this opens a visible tab for long-running work and directs reuse through send_to_session, but it does not explain lifecycle effects such as whether the tab persists, how to clean it up, or what happens after opening.

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 tightly written sentences, front-loaded with the core action and followed by selection guidance. Every sentence earns its place by clarifying when to use this tool and which sibling to use instead.

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 tool with full schema coverage and no output schema, the description covers purpose, usage conditions, and alternatives well enough to invoke it correctly. It could mention lifecycle cleanup or resource implications, but those are secondary to correct selection.

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 are documented in the schema. The description adds only the notion that the tab is 'named' and gives usage examples, but does not add syntax, defaults, or constraints 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 uses a specific verb and resource: 'Open a new named terminal tab.' It clearly distinguishes this tool from command-execution and session-reuse siblings, so an agent can identify its role without inspecting the schema.

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

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

It gives explicit when-to-use guidance ('ONLY use for long-running commands that need their own visible tab'), concrete examples (builds, installs, servers, cloning repos), and named alternatives for quick commands and existing sessions. Nothing important is left 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 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?

With no annotations, the description carries the full burden and does well: it discloses the data sources (global inbox plus every registered project's `replies.jsonl`) and the sort order (most-recent-first). It omits any statement about return shape or how `limit` interacts with the cross-project aggregation, which keeps it from a 5.

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

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

Front-loads the core identification in the first sentence and follows with scope and then use cases. The two quoted example questions are useful framing, though the `replies.jsonl` file-path detail is closer to implementation trivia than agent-facing guidance.

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 read tool with three optional, fully documented parameters and no output schema, the description covers scope, ordering, and typical questions it answers. It stops short of describing the returned reply records, which an agent might want given there is no output schema.

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

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

Schema description coverage is 100%, so all three parameters are already documented, setting the baseline at 3. The description adds only indirectly, via the most-recent-first ordering that gives `limit` meaning; it says nothing extra about `search` or the `project` basename matching that the schema doesn't already cover.

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 (browse the OUTBOUND history of replies sent via `reply_to_user`) and capitalizes OUTBOUND to contrast with the sibling `read_user_inbox`. An agent can immediately tell this reads sent messages, not received ones.

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

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

Gives concrete when-to-use examples ("what was the last thing you said in this project?", "what did you tell me about X?") and names the originating tool `reply_to_user`. It lacks an explicit when-not / alternative-sibling statement (e.g. 'for inbound messages use read_user_inbox'), so it stops short of a 5.

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

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

With no annotations, the description carries the load and does well: it discloses that the session is not resumed, documents the pointer-file resolution and largest-.jsonl fallback, and describes the output markers ([used: <tool>], [thought]) and truncation. It stops short of saying what happens when a project name matches nothing, which matters for a read tool with no annotations.

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

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

Front-loaded with purpose, then usage, then resolution, then return shape — a sensible order with no filler sentences. Slightly dense in the resolution sentence, but every clause (precedence, fallback, markers) carries 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?

There is no output schema, and the description compensates by describing the formatted turn output, inline tool/thinking markers, and truncation behavior. The main residual gap is failure modes (unknown project, stale pointer, empty transcript) for a tool with no annotations to lean on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema by explaining how `project` is resolved (inbox pointer, then fallback) and that session_id overrides project. It does not restate ranges for last_n/max_body_chars, which is fine since the schema covers them.

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

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

Names a specific verb and resource ('Read the most recent N turns of a Claude Code session's transcript') and adds the crucial negative scope 'without resuming it,' which separates it from send_to_session/list_sessions. An agent can tell exactly what it gets back from the opening clause.

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

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

Gives concrete trigger phrases ('what's the status of project X?') and states the alternative approach it replaces ('you read the actual transcript instead of relying on memory'). It also spells out the resolution precedence: pass project for fuzzy lookup, or session_id for direct lookup, with session_id taking precedence.

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 discloses key traits: it drains unread notes, aggregates across global and project inboxes, lists returned note fields, and states that read messages are archived. That archiving detail is important because it implies a state-changing side effect beyond a pure read.

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 front-loaded with the core action and scope, then adds the return shape, archiving behavior, invocation trigger, and reply follow-up. Every sentence adds operational value; none is filler.

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

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

For a zero-parameter tool with no output schema and no annotations, the description is sufficiently complete: it explains the data sources, what each returned note contains, that read messages are archived, when to call it, and how to handle a `reply_token`. No critical detail needed to invoke it correctly appears missing.

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

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

The tool takes zero parameters, so there is no per-parameter syntax to explain; baseline 4 applies. The description still clarifies the implicit inputs—all registered project inboxes plus the global inbox—without contradicting 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?

States a specific verb and resource: 'Drain unread notes the user left for Claude' via `seashell-msg`, aggregated across global and project inboxes. It also distinguishes the read/drain action from the follow-up action `reply_to_user`, so the agent can tell what this tool does and what it is not 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?

Explicitly says when to call it: when the user's chat message is brief or implies they were elsewhere, with examples like '?', 'continue', and 'check inbox'. It also names the follow-up alternative `reply_to_user` when a `reply_token` is present, though it does not state when to prefer `inbox_history` or `inbox_count` instead.

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?

With no annotations, the description carries the burden and does well: it discloses the write target (replies.jsonl, global or per-project), the delivery latency (~1 second pickup by seashell-ask), and the blocking-caller semantics. It does not say what happens on a stale/invalid message_id or whether the call can fail silently, which is the remaining behavioral 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?

Four sentences, front-loaded with the action, then the trigger condition and the exclusion. Every sentence conveys either what to send, when to send it, or what happens after — no filler.

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

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

For a 3-parameter tool with no annotations and no output schema, the description supplies the workflow, the timing, and the write destination, which is enough to invoke it correctly. Missing only failure-mode guidance (invalid or already-replied message_id).

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 a 3 is the floor; the description adds value by explaining that replies land in a global or per-project file, which clarifies why project_path scoping exists and what it affects. It still does not tie message_id directly to the inbox record it must come from, but the schema covers that.

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 ("Post a reply to a user inbox message") that is instantly separable from siblings like read_user_inbox and read_my_replies. The description also identifies the upstream trigger (a message carrying a reply_token) so the agent knows which resource instance this acts on.

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?

States both the positive condition (message had a reply_token, user is blocking) and the negative case (a plain seashell-msg note needs no reply call — answer in chat). It names the sibling tools that produce each case, leaving nothing 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?

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 behavioral burden for a mutation tool. It never says whether saving overwrites an existing profile of the same name, where profiles are persisted, whether the directory must exist, or whether environment_vars are stored in plaintext — all material for a write 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 front-loaded sentence with the verb first and zero filler. The parenthetical slightly duplicates the schema's own field list, which costs it the top mark, but the definition is efficient and scannable.

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

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

For a five-parameter mutation with a nested object (environment_vars) and no annotations or output schema, one sentence is not enough. Collision/overwrite behavior, persistence location, and expected response (success only? returns the saved profile?) are all 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%, so each of the five parameters is already documented at the field level. The description's parenthetical restates the same fields without adding format, constraint, or default information beyond the schema, 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?

A specific verb ('Save') plus resource ('named workspace profile'), followed by a parenthetical enumerating exactly what is captured (directory, commands, env vars, terminal preference). This clearly separates it from load_workspace_profile, list_workspace_profiles and delete_workspace_profile, though it never names those siblings 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 'current project context' implies the moment to use it, but there is no explicit when/when-not, no mention of what happens if a profile with that name already exists, and no pointer to load_workspace_profile as the counterpart operation. Guidance is inferred from the name, not 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 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?

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?

No annotations are provided, so the description carries the full behavioral burden, yet it only says a command is 'suggested.' It does not state whether anything is executed, whether the suggestion is advisory only, where the suggestion comes from (model vs. template library), or what form the result takes. For a tool sitting alongside execute_command, this omission matters.

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 no filler and the key concept front-loaded. It is efficient, though its brevity stems partly from under-specification rather than disciplined editing.

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 structurally simple (one string parameter, fully documented, no nested objects), so a short description is defensible. Still, with no annotations and no output schema, the description leaves unresolved whether the returned suggestion is executed, how it is returned, and what the agent should do with 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?

There is a single parameter with 100% schema description coverage ("The user's request or task description"), so the schema already documents its meaning. The description restates the same idea ("based on the user's request") without adding format, length, or phrasing guidance, 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 states a specific verb and resource ("suggests a terminal command") and adds the basis for the suggestion ("based on the user's request"), which distinguishes it from execution-oriented siblings by name alone. However, it never explicitly contrasts itself with preview_command or execute_command, so differentiation is left to the agent's 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 preview_command or execute_command, nor whether the suggestion should be previewed/confirmed before running. The agent must infer that this generates rather than runs a 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 provided, the description carries the full burden and does disclose key traits: a dry-run confirmation gate, a hard dependency on the Seashell Helper, and that the operation is a multi-block mutation. It does not say whether existing blocks in the tab are replaced, preserved, or appended, which is the main remaining behavioral unknown for a mutation tool.

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

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

Four short sentences, front-loaded with the action and scope, followed by template options, the confirmation protocol, and the prerequisite. No filler or redundancy.

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

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

Covers the prerequisite, the confirmation workflow, and the meaningful template choices, which is most of what an agent needs. For a mutation tool with no annotations and no output schema, the one notable omission is the effect on pre-existing tab content and what the confirmation response 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 four parameters are already documented, and the description largely restates the template list rather than adding syntax or defaults beyond the schema. Baseline 3 applies since the schema does the heavy lifting.

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 ('Bootstrap a Wave tab with a project-specific block layout') and enumerates the available templates, which makes the tool's scope concrete. It does not name the nearby alternatives (wave_create_block, run_template, list_templates) that an agent might confuse it with, so the differentiation is only 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?

Gives clear procedural guidance for the two-phase invocation: the first call returns a confirmation and only approved=true executes, which prevents accidental side effects. It also names the Seashell Helper prerequisite. It stops short of stating when to prefer this over wave_create_block or run_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. It mentions the prerequisite but omits critical behavioral details such as return values, error handling if the helper is not running, or whether the connection is idempotent. This is a significant gap for a connection 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 sentences, front-loaded with the purpose and then the prerequisite. Efficient and easy to parse, though slightly more context could be added without hurting conciseness.

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

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

Given the lack of annotations and output schema, the description should explain what happens after connection (e.g., success state, side effects) and any error conditions. It covers the prerequisite but leaves the agent guessing about the outcome.

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 score is 4. The description does not need to explain parameter semantics beyond what the empty schema already conveys.

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 ('Connect') and resource ('MCP server to the Seashell Helper block'), clearly distinguishing it from sibling tools like wave_helper_status or wave_list_blocks. However, it does not explicitly name an alternative, 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?

It provides a prerequisite ('The helper must already be running') which implies when to use it, but gives no guidance on alternatives or when not to use it. The condition is helpful but not comprehensive.

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 the full behavioral burden. It usefully discloses the confirmation/approval gate and the helper-block dependency, but says nothing about what happens when the helper is absent, whether the block persists, or what errors look like for a mutating 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?

Three short sentences with the purpose front-loaded, followed by the execution protocol and the prerequisite. Nothing is repeated and no sentence 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 nine-parameter mutation with no annotations and no output schema, the description covers the approval flow and dependency but leaves the result of the confirmation call and post-creation state unstated. Adequate to invoke, thin for understanding consequences.

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 nine parameters are already documented in the schema, including view types, cwd, url, file, and approved. The description adds no param-level meaning beyond the schema, which is the expected baseline at full coverage.

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 ('Create a new block in Wave Terminal'), which distinguishes it from wave_list_blocks, wave_delete_block, and wave_run_in_block. It does not differentiate itself from wave_create_widget, which is a nearby sibling that also creates things, 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?

Explains the two-step confirmation protocol ('First call returns a confirmation; pass approved=true to execute') and states the prerequisite ('Requires the Seashell Helper block'), which is genuinely decision-relevant context. It gives no when-not guidance or routing against alternatives such as open_terminal_tab or wave_create_widget.

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

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

With no annotations at all, the description bears the full behavioral burden. It earns credit for disclosing the dry-run/confirm pattern (first call has no side effect), but says nothing about what happens if a widget with the same id already exists, whether Wave must be running, or whether the widget persists across restarts.

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, zero filler, and the identification of the tool comes first followed by the operational instruction. Nothing here could be cut without losing 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?

For a 5-parameter mutation tool with no annotations and no output schema, the description covers purpose and the confirmation protocol but leaves duplicate-id behavior, error modes, and any environment prerequisites unstated. Adequate to invoke correctly, thin on what the agent should expect.

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 every parameter has a documented default in the schema, so the baseline applies. The description's only parameter-related content is the approved=true instruction, which restates the schema's own "Set to true to confirm".

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?

"Add a Fish shell widget to the Wave widget bar" gives a specific verb and resource, and the parenthetical explicitly ties it to wave_create_widget as a specialized convenience wrapper, which separates it from the generic sibling. It stops just short of 5 because it doesn't say what this wrapper does differently from calling wave_create_widget with fish-specific arguments.

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 two-step flow is spelled out: the first call returns a confirmation and approved=true executes, so an agent knows exactly how to drive it. It doesn't tell the agent when to prefer this over wave_create_widget or list_templates, but the wrapper framing makes the choice largely implicit.

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

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

No annotations exist, so the description carries the full burden, and it does disclose the key traits: this is a mutating write scoped to ~/.waveterm/widgets.json, and it is gated behind a two-phase approval. It omits what happens if 'id' collides with an existing widget (overwrite vs. error) and any permission/file-existence 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 tight sentences: purpose and side effect first, then the approval mechanic. Nothing is redundant and no sentence could be removed without losing a decision-relevant fact.

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 12-parameter mutation tool with no annotations and no output schema, the description covers purpose, write target, and the approval gate, and it even hints at the first-call return value. It is slightly thin on duplicate-id behavior and what a successful approved call returns, but nothing critical to calling it correctly is absent.

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 all 12 parameters, including the nested env object, are documented in the schema, so the baseline is 3. The description reinforces only the approved flag's role in the confirmation flow and adds no semantics for id, view, env, or the defaulted booleans.

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?

Uses a specific verb + resource ('Create a new custom widget in Wave Terminal') and names the persistence target, which distinguishes it from read-side siblings like wave_get_widgets and from wave_update_widget. It never explicitly contrasts itself with near-neighbors such as wave_create_fish_widget or wave_create_block, so it stops short of full sibling differentiation.

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

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

Gives a concrete procedural rule: the first call is a confirmation stub and the write only happens on a follow-up with approved=true. That is actionable guidance an agent would otherwise have to discover by trial. It does not say when to prefer this over wave_create_fish_widget or save_template, so no explicit 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 carries the full behavioral burden. It usefully discloses the confirmation flow and helper-block prerequisite, but it does not state whether deletion is irreversible, what permissions are required, or what happens to existing block state.

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 core action, followed by the confirmation flow and prerequisite. Every sentence contributes directly to correct invocation.

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

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

Given two parameters, no output schema, and no annotations, the description covers the essential execution flow and prerequisite. It is nearly complete for invocation, though it leaves out post-deletion behavior and failure modes.

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

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

Schema description coverage is 100%, so the schema already defines block_id and approved. The description adds the first-call confirmation behavior around approved, but does not add substantial meaning beyond the schema for either parameter.

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: deleting a block in Wave Terminal. It is distinguishable from widget-related siblings, but it does not explicitly contrast with wave_delete_widget or other deletion 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 clearly explains the two-step invocation flow (first call returns confirmation, then approved=true) and names the prerequisite Seashell Helper block. It does not describe when to avoid this tool or when to use an alternative deletion tool.

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 most important behavior: this is a destructive, two-phase operation requiring explicit approval. It stops short of stating irreversibility or what happens for an unknown id.

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

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

Two short sentences, zero waste, with the confirmation requirement front and center before the agent acts.

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 destructive tool with no annotations and no output schema, the essential information (what it deletes, the approval handshake) is present. Minor gaps remain around the confirmation response shape and error handling for invalid ids.

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 description reinforces the approved workflow but adds no syntax or identifier-format detail beyond it.

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 ('Remove a custom widget from Wave Terminal'), which cleanly separates it from sibling mutators like wave_create_widget and wave_update_widget. Scope of the resource (custom widget) is explicit.

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

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

Gives concrete operational guidance: the first call returns a confirmation and a second call with approved=true executes. It does not, however, contrast with wave_delete_block or explain when deletion is appropriate versus updating the widget.

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 burden and discloses the important confirmation workflow and helper-block prerequisite. It does not describe error behavior or full side effects, but it gives the key behavioral context 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?

Three short sentences, front-loaded with the core action, followed by the confirmation rule and prerequisite. There is no wasted language.

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 tool with no annotations and no output schema, the description adequately covers the action, approval flow, and prerequisite. It stops short of explaining file existence requirements, failure modes, or the exact confirmation response, but it is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents file, tab_id, and approved. The description reinforces the approved workflow but adds little parameter meaning beyond the schema text, so the 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 states a specific verb and resource: opening a file for editing in Wave Terminal. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling wave_view_file.

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 explains the two-step usage flow: the first call returns a confirmation and approved=true executes. It also states the Seashell Helper block prerequisite, but it does not name alternatives or when not to use this tool.

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

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

With no annotations, the description carries the full behavioral burden. "List" and the file path imply a read-only operation, but it does not explicitly state side-effect behavior, what happens if the presets file is missing, or how results are 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 front-loaded sentence that identifies the action, resource, and data source without filler.

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

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

For a zero-parameter read-only listing tool, the description gives enough context to invoke it correctly. It could mention return format or missing-file behavior, but no output schema exists and the core operation is clear.

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 is no parameter semantics gap. The description adds nothing needed beyond the schema, which is appropriate here.

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?

Uses a specific verb ("List") and resource ("AI model presets configured in Wave Terminal"), and adds the source file path. An agent can distinguish this read operation from sibling mutation tool wave_set_ai_preset.

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 "List all" implies inspection/read usage, but the description does not explicitly say when to use this instead of alternatives such as wave_set_ai_preset. No exclusions or prerequisites are stated.

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

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

With no annotations, the description carries the full burden, and it does add real behavioral context by naming the backing file (~/.waveterm/backgrounds.json), which tells the agent this reads local disk state rather than live app memory. However, it says nothing about what happens if that file is missing, whether entries include image paths vs. color values, or whether the result can be empty. A read-only list tool is low-risk, but the disclosure stops short of full transparency.

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

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

A single, front-loaded sentence with no filler. The resource is named first and the supporting detail (source file) follows in parentheses, which is exactly the right ordering.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description covers the essential who/what: it lists tab background definitions from a specific file. The one remaining gap is the shape of the returned entries (names, colors, image paths), which an agent might want before deciding how to present results, but that is a minor omission for a simple listing tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies for a no-argument tool.

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 tab background definitions in Wave Terminal'. The parenthetical source path (~/.waveterm/backgrounds.json) further pins down exactly what data is returned. It doesn't explicitly contrast with siblings like wave_get_settings or wave_get_widgets, but no sibling overlaps this resource, so disambiguation is implicit 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?

There is no guidance on when to reach for this tool versus wave_get_settings or wave_get_widgets, and no note that it is a read-only inspection of a local config file. The only implicit cue is the word 'List', which signals a retrieval operation. Nothing states prerequisites (e.g., whether Wave Terminal must be installed) or what to do when no backgrounds are defined.

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 implies a read-only operation via 'Get' and discloses an important dependency (Seashell Helper), but it does not describe return format, scrollback limits, or error behavior.

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

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

Two short sentences with zero waste, and the primary purpose is front-loaded before the dependency requirement.

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 read tool, the description covers purpose and a key prerequisite. Without an output schema, though, it should say more about what scrollback content is returned or any limits, leaving a noticeable 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 coverage is 100%, so both parameters are already documented in the input schema. The description adds no additional meaning about block_id or last_command_only beyond what the schema provides, making baseline 3 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 states a clear verb ('Get') and resource ('terminal scrollback content') scoped to a Wave block. It distinguishes from generic command execution tools by naming scrollback specifically, though it does not explicitly contrast with siblings like get_command_output.

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

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

It gives the prerequisite ('Requires the Seashell Helper block'), which is useful context for when the tool is usable. However, it does not say when to choose this over alternatives such as get_command_output or wave_run_in_block, leaving selection 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 present, the description carries the full burden. It usefully discloses the backing file (~/.waveterm/settings.json), confirming a read-only operation against local disk, but says nothing about what is returned, whether sensitive values are redacted, or error behavior if the file is missing.

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 source location is front-loaded before the optional filter behavior. Every clause earns its place.

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

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

For a single-optional-parameter read tool this is nearly self-sufficient: the agent knows the source file and how to narrow results. The only gap is return shape, but with no output schema and a trivially predictable key/value result, that omission is minor.

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 parameter is already documented as an optional namespace prefix. The description only restates the same examples ('ai', 'term', 'window', 'app') without adding matching semantics — e.g. whether the prefix is a substring or dot-path match, or what happens when no match exists.

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') and resource ('Wave Terminal settings') plus the exact source file (~/.waveterm/settings.json). It is distinguishable from the mutating sibling wave_set_setting by the read-only framing, though it never names that 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 optional namespace filter is explained with concrete examples, giving implied usage context, but there is no explicit guidance on when to call this versus wave_set_setting or the other wave_get_* siblings, and no 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?

No annotations are provided, so the description carries the burden. It does add useful context by disclosing the data source (~/.waveterm/widgets.json), which implies a local file read, but says nothing about behavior when the file is absent or malformed, nor about whether the read reflects on-disk state versus runtime state.

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

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

A single front-loaded sentence with zero filler; the scope and source are both delivered before any trailing detail. Nothing could be removed without losing 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?

With no parameters, no annotations and no output schema, the description covers what is needed to select the tool. The one remaining gap is that with no output schema an agent doesn't know the shape of returned widget records (names, IDs, fields), though this is a minor omission for a simple listing call.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema property bag is empty and consistent with the description's 'all widgets' scope.

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 'List' plus a precisely scoped resource ('all custom widgets configured in Wave Terminal'), with the backing file named. This clearly separates it from the mutation siblings wave_create_widget / wave_update_widget / wave_delete_widget, though it doesn't address whether fish widgets (wave_create_fish_widget) are included in the listing.

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 explicit when-to-use or when-not-to-use statement and no named alternative. For a zero-parameter read-only listing the usage is largely implied by the name and verb, so the gap is minor rather than misleading, but an agent gets no routing 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 burden. It discloses the two pieces of information returned (connection state, tool tier), which is useful, but says nothing about whether the call has side effects, how quickly it returns, or what an error/disconnected state 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?

Two short sentences, both front-loaded with the most important information; nothing is wasted.

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

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

For a zero-parameter read probe with no output schema, the description conveys enough: what is checked and what is reported. A slightly fuller note on the possible values or the relationship to wave_connect_helper would make it 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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond the schema. The mention of 'tool tier' usefully hints at what the call reports.

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 ('Check whether the Seashell Helper block is connected') plus the secondary output (available tool tier). An agent can tell this is a read-only status probe, though it never names the sibling it complements (wave_connect_helper) to sharpen differentiation.

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: call it to see if the helper is connected and which tier is available. No explicit when-to-use guidance relative to wave_connect_helper, self_check, or check_interactive, and no stated 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 carries the behavioral burden and does disclose the required Seashell Helper block prerequisite. It implies a safe read via 'List' but does not cover pagination, error behavior, or what happens if the helper is unavailable, leaving meaningful gaps.

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 two sentences, front-loads the main action, and contains no waste. The prerequisite is placed after the core purpose without obscuring it.

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 filtered list tool, the description covers the core action, filters, and a key prerequisite. But with no annotations and no output schema, it omits expected return content and behavioral details such as pagination or helper-missing errors.

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 input schema already documents all three filter parameters. The description mentions the same filter categories, matching the schema, but adds no extra parameter semantics beyond that.

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 blocks in Wave Terminal,' and adds optional filters. It is clear enough to distinguish from block mutation tools and workspace listing tools, though it does not explicitly name sibling alternatives.

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 explains optional filtering by workspace, tab, or view type and notes the Seashell Helper dependency, which gives useful usage context. However, it does not say when to choose this tool over related listing or environment tools, and it gives no explicit exclusions.

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