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

With no annotations, description carries full burden. It discloses dependencies (git), scope (files only), and return format ({checkpoint_id}). Could add detail on persistence or failure modes, but sufficient for safe usage.

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 that front-load the purpose and immediately add requirements and limitations. Every phrase adds value; no filler.

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

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

In the absence of an output schema, the description specifies the return value. It explains what the tool does and its constraints. Missing details on checkpoint lifecycle or restoration, but adequate for a simple tool.

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

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

Schema coverage is 100%, so both parameters have descriptions. The description adds no extra parameter-specific meaning beyond what the schema provides, meeting the baseline of 3.

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

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

The description states it takes a workspace checkpoint (snapshot of files) on a remote session. It clarifies it's a file-only operation and distinguishes from sibling tools by emphasizing its scope and requirement for git.

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 clear context: requires git on remote host, undoes files only, no side effects. Implies when to use (file snapshot) but does not explicitly contrast with siblings like session_restore or session_checkpoints.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds one genuinely useful behavioral fact beyond the annotations, the newest-first ordering, but says nothing about pagination, result size, or how checkpoints relate to session_restore. Adequate but thin for a read 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 sentence with no waste, with the resource and the ordering constraint front-loaded. It could be a shade more informative without losing brevity, but nothing needs trimming.

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 read-only list tool with full schema coverage and no output schema, the description covers the essentials. It does omit what a checkpoint represents and how the listing is used downstream (session_restore), which would help an agent place it in the workflow.

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 schema already explains that session_id comes from session_create. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('checkpoints') scoped to a remote session, and adds ordering ('newest first'). It does not explicitly distinguish itself from the singular sibling session_checkpoint, but any agent can tell a listing operation apart from the others.

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 when-to-use guidance, no mention of the related siblings (session_checkpoint for creating one, session_restore for consuming one), and no prerequisites or exclusion criteria. The intent of a list tool is implied but nothing routes the agent between this and its cluster mates.

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 statefulness, secret-redacted output, that remote checkpoints require git plus an explicit workspace and never default to home, and the key-selection fallback ("if the server rejects that key, no other key is tried"). It omits session lifecycle (expiry, limits, need to destroy) and overall error behavior, so it falls short of exhaustive.

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

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

Front-loaded with the core action, and every sentence carries information. It is a single very dense run-on paragraph, however, with topics (auth, checkpoints, budgets) packed together rather than grouped, which costs readability for a 15-parameter tool.

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 complex 15-parameter tool with no output schema and no annotations, it covers purpose, transport-specific requirements, checkpoint semantics, and states the return value (session_id). Missing pieces are session lifecycle and concurrency/error expectations, which are not derivable elsewhere.

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 already 100%, so the baseline is 3; the description adds value by stating cross-parameter relationships the schema does not, e.g. ssh needs host plus password or key_path, docker needs container, and workspace must be set for checkpoints while auto_snapshot/paths/checkpoint_ignores tune them. That is meaningful semantics beyond the per-field text.

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

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

Opens with a specific verb and resource: "Open a stateful shell session." It immediately scopes the tool (stateful vs. built-in/inline shell) and enumerates the transports it supports, so an agent can tell it apart from session_exec or session_destroy without inspecting schemas.

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

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

Gives explicit selection criteria: use this "when you need: cwd/env kept across calls, SSH, Docker, secret-redacted output, or undoable remote file changes (checkpoints); local has no checkpoints." It also states the per-transport prerequisites (ssh needs host + password or key_path; docker needs container), which is effectively when-it-applies 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?

Annotations already declare destructiveHint=true, so the safety bar is partly covered. The description nonetheless adds real behavioral detail beyond the annotation: the session_id is invalidated immediately and unsaved shell state (cwd, env, background jobs) is lost. It stops short of stating whether the operation is reversible or what happens on an already-invalid 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 tight sentences with the destructive warning front-loaded, followed by the concrete consequences. No filler, 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-parameter destructive tool with an annotation covering the safety profile and no output schema, the description supplies the missing consequence detail (invalidated id, lost shell state). It is nearly complete, lacking only error/idempotency behavior for repeated calls.

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 exists and schema coverage is 100%, with the schema itself noting the id comes from session_create. The description adds no format or constraint detail 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?

States a specific verb and resource ('destroy a session and free its resources') and makes the destructive scope explicit. An agent can immediately distinguish it from siblings like session_create, session_restore, and session_checkpoint.

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

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

The description implies the tool is for teardown ('free its resources') but never states when to choose it over alternatives such as session_list or session_restore, nor any prerequisite like completing work first. Usage is inferable from the destructive framing rather than explicitly guided.

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

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

Goes well beyond the openWorldHint/destructiveHint annotations: timeout semantics (exit_code 124, timed_out:true, session remains usable), default and max timeout values, session termination triggers ('exit', or a `set -e` failure), and the guarantee that budget shaping never changes exit code or side effects. The redaction caveat ('never write it back to a file') is a genuinely non-obvious safety detail.

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 and return shape, and every clause carries information with no filler. However, the heavy semicolon chaining and nested parentheticals make the constraints harder to scan than they need to be; a few of the later sentences could be tightened.

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 compensates by enumerating the returned fields, documenting timeout and session-lifetime behavior, and covering output shaping and redaction. An agent has everything needed to invoke this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining budget semantics that the schema only names - the grep -> line-keep -> char-cap ordering, that it runs after redaction, and that it emits a report (mode + lines_total/lines_kept). It also restates the timeout override/clamp behavior, so most of the gain is on the budget 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?

Opens with a specific verb+resource ('Run a command in a session') and immediately states the return shape (ExecResult JSON with stdout, stderr, exit_code, duration_ms, cwd, truncated). No sibling does execution, so an agent can route here unambiguously without opening a 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?

Explicit when-not conditions ('Non-interactive: stdin is closed - no prompts, REPLs, or editors') plus the concrete workaround ('use `sudo -n`'). Also covers the tricky case of long jobs ('nohup CMD > /tmp/x.log 2>&1 &' then poll `cat /tmp/x.log`), which is exactly the guidance an agent needs to avoid a hanging call.

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?

Annotations already declare readOnlyHint=true. The description adds valuable behavioral context beyond that: sessions may have been closed by `exit`, a `set -e` failure, or idle-timeout reaping, which explains why list results can differ from expectations. It does not cover pagination or ordering, but that is minor for a live-session list.

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 return shape, then the decision criteria. No filler; 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?

With no parameters and no output schema, the description fully carries the burden: it states what is listed, the fields returned, and the reasons a session might be missing. An agent has everything needed to call and interpret 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter commentary and instead documents the return shape, which 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?

States a specific verb and resource ('List live sessions') and enumerates the returned fields (session_id, transport, idle_secs). This clearly distinguishes it from siblings like session_checkpoints, session_create, and session_exec.

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 names two use cases: recovering a lost session_id and verifying a session is still open before calling session_exec again. It also names the sibling it precedes, giving the agent a clear routing 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?

Goes well past destructiveHint=true by specifying exactly what is destroyed (untracked files anywhere under the workspace), that it is permanent and unprompted, what is reverted (tracked files), and what it explicitly does NOT cover (DB writes, network calls, installs). This is the rare case where the description meaningfully upgrades the annotation.

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

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

Three sentences, front-loaded with the DESTRUCTIVE marker, then the action, then the blast radius and limits. No filler, and the most decision-critical fact (permanent deletion without prompt) is placed before the caveats.

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 mutation with no output schema, the description covers action, default, destruction scope, and side-effect limits, which is nearly everything an agent needs. It omits any statement of return value or failure conditions (e.g. unknown checkpoint_id, inactive session), which would close the last 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%, so both parameters are already documented, including the 'omit to restore the most recent' default. The description restates that default without adding format, validity, or lookup details, so the schema carries the load and 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?

States a specific verb and resource — restoring a session's workspace to a checkpoint — with the scope ('remote session's workspace') and default behavior spelled out. The restore-vs-create contrast with sibling session_checkpoint is unambiguous from the verb alone, so an agent can route correctly without opening any schema.

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

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

Gives a concrete selection rule for the ambiguous case ('omit checkpoint_id to restore the most recent') and makes the destructive context explicit so the agent knows this is not a routine read. It never names an alternative tool or states a precondition (e.g. session must be active), so it stops short of full when/when-not guidance.

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