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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description adds genuinely new behavior: the in-flight prompt settles with stopReason "cancelled" and no other session is affected. It names the underlying ACP session/cancel call and clarifies the effect on running work, though it omits the post-cancel session state (still open? resumable?).

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, front-loaded with the action and its scope, with no redundant restatement of the name or schema. Every clause 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?

For a one-parameter destructive tool with annotations covering the safety profile and no output schema, this is nearly complete: it explains what happens to running work and the isolation guarantee. The remaining gap is the resulting session lifecycle state, which matters given the dsh_resume_session and dsh_close_session 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% for the single session_id parameter, which is already documented as the explicit session id to cancel. The description's 'exactly one session' reinforces the cardinality but adds no format or lookup guidance 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 (cancel/stop the work) and resource (one session), and the phrase 'exactly one session' plus 'other sessions are untouched' pins the blast radius. It does not explicitly distinguish itself from the sibling dsh_close_session, which a reader could plausibly confuse with cancellation.

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 'stop the work of exactly one session', which suggests interrupting a running prompt, but there is no explicit when-to-use versus when-not guidance. It never says whether to prefer this over dsh_close_session or whether the session can be resumed afterward with dsh_resume_session.

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 annotations by spelling out the exact sequence of effects (cancels in-flight work, drains updates, flushes persistence, releases the run scope) and, crucially, what is preserved (persisted history, resumable later). Annotations only flag destructive=true; the description tells the agent what is actually destroyed versus retained.

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 operation and target, followed by effects and then constraints; every sentence carries signal. There is mild redundancy — the not-read-only caveat appears in both the description and the confirm parameter, and the confirm requirement is restated.

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 tool with annotations and no output schema, the description covers effects, side effects, and data retention adequately. It does not state behavior for an invalid or already-closed session id, which leaves an edge case 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?

With 100% schema description coverage, both parameters are already documented, including the confirm=true requirement and the meaning of session_id. The description adds only the 'exactly one session' scoping nuance, so the schema does the heavy lifting 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 ('Close exactly one session via ACP session/close') with an explicit scope of exactly one session, and contrasts it against a read-only inspection use case, so an agent can tell what it does without opening 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?

Gives clear conditions: requires confirm=true, must not be used to inspect a session, and notes history is retained and resumable later, which points toward dsh_resume_session. It stops short of explicitly distinguishing itself from the sibling dsh_cancel_session, which also affects in-flight work — that choice 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?

Annotations already declare it is a non-read-only, non-destructive, non-idempotent operation. The description adds real behavioral context beyond that: cwd is path-validated and realpath-canonicalised before use, and model/reasoning_effort are gated by bridge allowlists. It does not cover failure modes or what is returned, but for a creation tool this is solid added value.

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 tight sentences, front-loaded with the operation and followed by the validation rules. There is no filler or restatement of the tool name.

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 indicate what a caller gets back (for example a session id needed for dsh_send_message or dsh_close_session) and whether sessions persist until closed. Those gaps are notable for a session-creation tool, though the validation rules are 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%, so the baseline is 3, but the description adds constraints the schema does not state: the allowlist requirement for cwd and the realpath canonicalisation step. These are meaningful semantics for the most important parameter, lifting it above 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 names a specific verb and resource ('Create a fresh persistent DSH session') plus the underlying call ('ACP session/new'). The word 'fresh' implicitly contrasts with dsh_resume_session, but no sibling is named explicitly, so differentiation is only partly achieved.

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 context is implied by 'fresh' versus the sibling dsh_resume_session, and preconditions are stated, but there is no explicit statement of when to prefer this over resuming or how it relates to dsh_list_sessions. The agent must infer the routing 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds traits annotations cannot express: results come from ACP session/list, are ordered newest first, only root sessions are included, and cross-process activity is invisible to ACP so a listed session may be locked by the desktop app. That last warning is a genuinely non-obvious behavioral hazard an agent would otherwise get wrong.

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 purpose, then filtering constraint, then return shape, then the capitalized warning. No filler, and the ordering places the operational caveat where it is most likely to be read before 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?

For a read-only three-parameter list tool with no output schema, the description covers purpose, filtering constraint, ordering, returned fields (sessionId/cwd/title/updatedAt), and pagination via the schema's cursor. Nothing an agent needs to call it correctly or interpret results is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not state: cwd must be an absolute path inside the allowed directories (the schema only mentions realpath validation). It also clarifies that limit bounds 'summaries' rather than full session records.

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 persisted, resumable DSH root sessions") plus the underlying source (ACP session/list) and ordering (newest first). Against siblings like dsh_create_session and dsh_resume_session, there is no ambiguity about which tool enumerates 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?

The description establishes the context for calling it (enumerate persisted root sessions, optionally narrowed by cwd) and supplies a non-obvious caveat that governs how to act on results: listed sessions may be held by the desktop app, so visibility does not imply availability. It does not explicitly name a sibling or say 'call this before dsh_resume_session', so it falls short of full when/when-not routing.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false. The description adds genuine context the annotations cannot: resuming activates the session, writes to the same persisted log, and can conflict with the desktop process that DSH ACP cannot detect. That is real value beyond structured fields, though it doesn't say what error surfaces on a log conflict.

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 action, then the scope limit, then the warning, then the precondition — a logical escalation. The session/list aside about desktop-held sessions is somewhat tangential to invoking this tool and could be trimmed, but every sentence carries operational weight.

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 mutation tool with no output schema and four fully described parameters, the description covers the safety profile, the ownership precondition, and the concurrency hazard. It omits what a successful resume returns (session state, resumed cwd) and how a detected desktop conflict is reported, which an agent would want before acting.

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 still adds meaning by explaining that acknowledge_released is a release confirmation and that 'switching desktop tabs does not count as releasing', which sharpen the schema's wording. It explains cwd validation and the permission_policy non-inheritance rule, but the latter is already spelled out fully in the schema.

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

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

States a specific verb ('Restore') plus resource ('persisted inactive DSH session') and the mechanism ('ACP session/resume'), then immediately bounds it: 'Resume only restores a persisted inactive session... it does not replay prior transcript messages.' That boundary cleanly separates it from dsh_create_session and dsh_send_message without needing to open their 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 when-not conditions (does not replay transcript, cannot see sessions held by another process, do not resume while the desktop may still be running it) plus a hard precondition ('Requires acknowledge_released=true'). It stops short of naming the sibling to use instead when a session is not persisted or is currently held by the desktop, so the alternative routing is implied rather than 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?

Adds substantial behavior beyond the annotations: the call blocks until the turn settles, one prompt per session at a time, agent_thought_chunk content is filtered out unless DSH_CODEX_INCLUDE_THOUGHTS is set, and DSH tool permission requests default to DENIED unless permission_policy is 'allow_once'. These are exactly the non-obvious traits an agent needs before invoking a mutating, potentially long-running call.

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, each carrying distinct information: action, concurrency constraint, return shape, and permission/thought defaults. The action is front-loaded and no sentence is filler or duplicated from 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?

Even without an output schema, the description summarizes the return payload (assistant text, tool-call summary, usage) and covers blocking behavior, concurrency, and permission defaults. For a 4-parameter mutation with full schema coverage and annotations, nothing material is left unexplained.

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 consequence-level meaning by explaining what permission_policy actually governs (DSH tool permission requests default to deny, never auto-approved) and that permission is per-turn. That goes beyond the schema's 'How to answer DSH tool permission requests for this turn.'

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 concrete verb and resource ('Send one user text message to an existing session via ACP session/prompt') plus the synchronous settle semantics. This is unmistakably different from the sibling session-management tools (list/create/resume/cancel/close), which do not carry payloads into a turn.

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?

Implies the prerequisite clearly ('existing session') and states an operational constraint ('Exactly one prompt may be in flight per session'), which tells the agent not to fire concurrent sends. It stops short of naming an explicit alternative or spelling out the create-then-send sequence, so it is strong context rather than a full routing rule.

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