dsh-baton

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 meaningful behavior: exactly what is torn down (turn, sub-agents, background jobs) and an important boundary — queued messages are NOT removed. It omits error/idempotency behavior, permissions, and what happens if nothing is running, so it is not fully complete.

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: the core action and its scope come first, and the queue caveat follows. Every clause carries information; nothing is padded.

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-param, no-output-schema cancel tool with no annotations, the description covers the essential questions: what stops, what survives, and how to target the session. Return/error semantics and whether the call is idempotent are unstated, which is the 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?

Schema description coverage is 100%, so the schema already documents both parameters; baseline is 3. The description only adds that the two keys are alternatives ('by run_id or session_id'), a small increment beyond the schema's field descriptions.

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

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

Specific verb ('Stop everything a session is doing') plus explicit scope enumeration (running turn, sub-agents, background jobs) makes the operation unambiguous. It does not name any sibling tool, but no sibling in the list performs cancellation, so confusion risk is low.

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

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

The description implies when to use it by naming the two lookup keys ('by run_id or session_id'), and the session_id note hints at the case where dsh-baton did not start the work. There is no explicit when-not guidance or named alternative, so usage is only implied.

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 load and does well: it discloses the side effect of creating a folder unless create_dir is false, states idempotent semantics for repeat calls, and flags an external plugin dependency. It omits error/permission behavior, but the important non-obvious traits are covered.

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 with zero filler. The primary action is front-loaded, followed by the conditional side effect, idempotency, and the dependency requirement in descending order of importance.

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

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

For a three-parameter registration tool with no output schema and no annotations, the description covers purpose, side effects, idempotency, and prerequisites. Only failure modes (invalid path, missing plugin) are left 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 all three parameters are already documented in the schema (path, title default, create_dir default). The description only restates the create_dir behavior, adding no syntax or format detail beyond structured data, 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+resource ('Register a folder as a workspace') plus the surface it affects (the DeepSeek Harness sidebar), which cleanly separates it from siblings like dsh_rename_workspace and dsh_list_workspaces. It stops short of explicitly naming which sibling to prefer in a given situation, but the action 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?

The description supplies real usage context: it is idempotent ('an already registered folder returns its existing workspace'), so an agent knows repeated calls are safe, and it names a precondition ('Needs the dsh-baton-host plugin'). It does not, however, say when to prefer or avoid this tool relative to alternatives.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It does add real behavioral traits: results are ordered newest first and are filtered to runs handed over via dsh-baton. It says nothing about pagination, truncation, the default limit's effect, or whether it is a read-only 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 sentence with zero filler. Ordering and source filter are front-loaded alongside the verb and resource, so every word earns its place.

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

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

For a simple one-parameter list tool with no output schema, the essentials are present. However, with no annotations and no output schema, an agent still cannot learn what a 'run' record contains or how listing interacts with limits — minor but real 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?

Only one optional parameter (limit) and schema description coverage is 100%, so the schema already carries the meaning. The description adds no syntax, bounds, or interaction detail beyond what the schema provides; 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 (runs) with scope ('recent') and ordering ('newest first'), plus the qualifier that runs came through dsh-baton. This is clear enough to distinguish from dsh_list_sessions and dsh_list_workspaces, 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?

No when-to-use guidance, no prerequisites, and no mention of any alternative. An agent cannot tell from the text whether dsh_list_runs or dsh_list_sessions is the right entry point for its question; the dsh-baton qualifier hints at context but is not a selection 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?

With no annotations, the description carries the full burden, and it does disclose real behavior: result ordering, the composition of each result, and the strong completeness claim that non-listed sessions are archived or gone. It omits pagination/total-count behavior around the limit parameter and any auth or cost notes, so it 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?

Three short sentences, zero filler, and the core purpose plus return shape is front-loaded before the routing and caveat sentences. Every clause carries information an agent needs.

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-required-param list tool with no output schema and no annotations, the description covers what is returned, in what order, what the list enables, and what its absence means. The only gap is the lack of pagination guidance for the limit parameter, which leaves minor ambiguity when more than 20 sessions 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 all four parameters are already documented (cwd, limit, query, include_subagents). The description only lightly reinforces semantics by tying "workspace folder (cwd)" to the returned field, adding no new syntax or filtering nuance 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 (list saved DeepSeek Harness sessions) plus ordering (newest first) and the fields returned (title, cwd, active-run flag). It is distinguishable from dsh_list_runs, dsh_list_workspaces and dsh_session_activity by resource, 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?

Gives a clear positive trigger ("Use it to find the session_id to continue") and a useful negative boundary ("Sessions not in dsh_list_sessions are archived or gone: do not look for them on disk"). It does not, however, name the alternative tools an agent should reach for when the intent is workspace or run listing rather than session listing.

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. It does add a real behavioral fact beyond the schema — the plugin dependency — which is valuable, but it omits read-only/mutation status, ordering, and pagination behavior for what is presumably a safe 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?

Two short sentences, front-loaded with the action and resource, then the dependency. 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?

For a zero-parameter list tool with no output schema and no annotations, the description covers what it does and the one non-obvious prerequisite. Return shape and ordering are unspecified, but there is no output schema promising that detail, so the gap 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. No parameter-related information is missing because the schema is empty.

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 (workspaces), and disambiguates the term by glossing it as 'project folders shown in the DeepSeek Harness sidebar.' That gloss is enough to separate it from dsh_list_sessions and dsh_list_runs, though those siblings are not 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?

Usage is implied by the verb and the sidebar gloss, and it usefully states the precondition 'Needs the dsh-baton-host plugin.' However, it never says when to prefer this over dsh_list_sessions or what to do if the plugin is absent, so the routing guidance is only implicit.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses content scope ('visible' conversation, includes tool names) without auth, error, or truncation behavior beyond the word 'recent'.

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 redundant clauses; the resource and its contents 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 a low-risk read tool with no annotations and no output schema, the description adequately conveys the shape of the return (prompts, replies, tool names) and the recency scoping. Only error/empty-session behavior is left 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 coverage is 100%, so both parameters are already documented. The description's 'recent' aligns with the `last` default but adds no format, ordering, or edge-case semantics 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?

Specific verb (read) and resource (recent visible conversation of one session), with the returned content enumerated (user prompts, assistant replies, tool names). It is clearly not the same as dsh_list_sessions or dsh_session_activity, but it never explicitly contrasts itself with those siblings.

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

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

There is no when-to-use statement, no mention of alternatives such as dsh_session_activity or dsh_status, and no preconditions (e.g., must the session exist or be active). The agent must infer the use case from the word 'conversation' alone.

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 does not meet it. 'Rename' implies mutation, but nothing is said about required permissions, whether the change is reversible, whether the title must be unique or length-limited, or whether an in-flight session can be renamed. The only added context is that the title appears in the sidebar.

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 verb and resource first and a short clarifying parenthetical. Nothing is wasted, though the sidebar note is the only non-obvious content in an otherwise terse line.

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 documented rename with no output schema and no annotations, the description is minimally sufficient to call the tool. It stops short of stating the mutation's side effects or constraints, which are the remaining gaps an agent would want covered.

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 two documented parameters ('New title', 'Session id'), so the schema already does the heavy lifting. The description adds no format, length, or constraint detail beyond what the schema states, which lands at 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?

States a specific verb (Rename) and resource (session), and the parenthetical clarifies which session surface is affected. It implicitly distinguishes itself from the sibling dsh_rename_workspace by naming 'session' rather than 'workspace', though it never calls that distinction out 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 versus alternatives, no prerequisites (does the session need to exist, be idle, be owned by the caller?), and no mention of the sibling dsh_rename_workspace which is the obvious near-miss for an agent choosing a rename 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 highest-risk behavioral fact: this changes only the sidebar title and does not move the folder. It omits other traits an agent might want, such as permission requirements, idempotency, or what happens when the identifier does not resolve.

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 a clarifying parenthetical; every clause earns its place and nothing is padded.

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 is needed for a rename, and the schema fully documents the arguments, so the description covers what is required to call it correctly. The one unresolved point is how the workspace is identified when only 'title' is marked required, which neither the schema nor the description clarifies.

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

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

Schema description coverage is 100%, so the baseline is 3. The sentence 'Identify it by workspace_id or path' restates the identifier parameters rather than adding format, constraint, or precedence rules (e.g. which wins if both are supplied).

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 ('Rename a DeepSeek Harness workspace') with an immediate scope qualifier ('sidebar title only; the folder is not moved'). The workspace vs. session distinction is implicit in the name, so an agent can separate it from the sibling dsh_rename_session.

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 parenthetical exclusion ('the folder is not moved') sets a clear expectation boundary, and 'Identify it by workspace_id or path' tells the agent how to target the tool. It does not, however, name an alternative tool or state prerequisites, so it stops 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?

With no annotations, the description carries the full behavioral burden and largely succeeds: it discloses the async return (run_id), that the turn runs in the background, the queue-vs-inject semantics, per-message run_ids, and the side effect that a non-workspace cwd is registered in the sidebar first. It omits error/permission behavior (e.g. invalid session_id) and any auth requirements, which is the only 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?

Purpose and the session-vs-new distinction are front-loaded, then behavior and the next-step handoff. It is dense and somewhat long, but nearly every clause carries actionable information (verbatim delivery, language guidance, run_id-per-message). Minor tightening possible in the message-authoring advice.

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 async dispatch tool with no output schema and no annotations, the description covers what an agent needs: what is returned (run_id), that the turn is backgrounded, how to retrieve the reply (dsh_wait or wait_command), mode selection, and the cwd side effect. Nothing essential to calling it correctly 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the role split between session_id (continue) and cwd/workspace_id (new session), including that cwd auto-registers a workspace. The mode/default semantics are largely duplicated from the schema's own descriptions.

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

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

Opens with a specific verb+resource ('Send a message to DeepSeek Harness') and immediately disambiguates the two entry modes: continue an existing session via session_id vs. start a new one via cwd/workspace_id. An agent can distinguish this from siblings like dsh_wait or dsh_list_sessions 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?

Explicitly states when to use which parameter (session_id vs cwd/workspace_id), when to use mode followup vs steer based on whether a session is already working, and names the follow-up tool ('wait for the reply with dsh_wait'). Routing to the next step in the workflow is 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 must carry the behavioral burden. It discloses the tool's scope (any-depth sub-agents, jobs, reminders, baton runs), which is useful and non-obvious, but says nothing about whether it is read-only, whether it blocks, how it behaves for an idle or unknown session, or what an error looks like. Adequate but incomplete for a tool with zero annotation coverage.

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 content enumeration is front-loaded ahead of the usage trigger. Every clause adds a distinct fact about coverage.

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

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

No output schema and no annotations, so the description is the only source of return-value information — and it does list the categories returned. For a single-parameter read tool that is close to sufficient; only the idle/error case and the read-only guarantee are 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?

One parameter with 100% schema description coverage, so the schema already documents session_id. The description adds no format, scope, or id-resolution detail beyond it. Baseline 3 applies when the schema does 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 resource (a session) and enumerates exactly what it reports: running turn, sub-agents at any depth, background jobs, reminders, and baton-handover runs. This is far more concrete than a generic 'get session status', though it never explicitly contrasts itself with the nearby siblings dsh_status or dsh_read_session, leaving the boundary 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?

Gives a clear trigger condition: 'Check this before sending to a session that might be busy.' That tells the agent when to reach for it. It stops short of naming alternatives (dsh_status, dsh_wait) or stating when this is the wrong tool, so it is context without 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?

No annotations are present, so the description carries the full burden and largely meets it: it discloses the non-blocking, one-off nature ('never a way to wait'), explains the non-obvious 'interrupted' state (Harness restart cut it short), and clarifies that human_interjections mean the result reflects that typed input. It does not mention permissions, rate limits, or whether the run is mutated in any way, which keeps it out of 5 territory.

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 tool's purpose is front-loaded in the opening phrase, and the routing advice is placed last where it belongs. However, the middle is one very long run-on sentence with a heavy parenthetical dump of states and fields, which taxes readability even though most clauses carry real 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, so the description must describe the return shape itself, and it does so comprehensively: state values, session_id, recent events, final reply, waiting_on, and human_interjections. Combined with the sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so both parameters (run_id, tail) are already documented by the schema, establishing the 3 baseline. The description alludes to 'recent events' without adding format or range guidance for tail, so it adds little beyond the schema 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?

The description states a specific resource and verb-equivalent ('Progress of a run') and then enumerates exactly what a caller receives: state, session_id, events, final reply, waiting_on, human_interjections. It also names the sibling it is not (dsh_wait), so an agent can distinguish it from the other run-related tools 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?

It gives an explicit when-not ('A one-off look, never a way to wait') and routes to the correct alternative ('to wait for the reply use dsh_wait'), including the retry case ('if dsh_wait timed out, call dsh_wait again'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 does so well: it discloses the 50 s server-imposed wait cap and why it exists (to stay under the client's tool timeout), the exact partial-failure shape (timed_out: true with only the state field), the retry contract, the no-progress-summary expectation, and that progress notifications are emitted only when the client requests them. These are operational traits an agent cannot get from 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?

Front-loaded with the core action and return value, then layered with the alternative-mechanism advice and the timeout/retry contract; every sentence carries information. It is somewhat dense with parenthetical asides, which slightly costs readability, but there is 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?

With no output schema and no annotations, the description covers the return contract itself ('final status and reply', plus the timed_out variant), the timeout and retry behavior, and the interaction with the sibling dsh_send. Nothing an agent needs to call this correctly and interpret the result 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?

There is a single parameter with 100% schema description coverage ('Run id from dsh_send'), so the schema already does the heavy lifting. The description adds one useful nuance beyond it: the same run_id is reused across repeated calls in the timed_out retry loop, which tells the agent the id is stable across invocations.

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 ('Wait for a run to finish') plus the return payload ('final status and reply'), which is exactly what an agent needs to decide between this and siblings like dsh_status or dsh_list_runs. It also explicitly names the competing mechanism (background wait_command in dsh_send), so it is distinguishable 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 an explicit preference rule with its precondition: use dsh_send's background wait_command 'when your client can run background shell commands and wake you when they exit', because it costs no turns. It also states the follow-up protocol for the timed_out case (call dsh_wait again with the same run_id, without summarising progress), which is when-to-use guidance for the retry path.

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