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 well: it discloses that queued messages are dropped, that a pending wait_thronglet surfaces a cancelled error, and that the session is idle afterward and accepts new messages. It does not mention authorization or permissions, leaving one gap 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?

Two dense sentences, front-loaded with the primary effect and back-loaded with post-conditions and the no-op case. No filler or restatement of the 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 one-parameter mutation with no annotations and no output schema, the description covers the key effects, side effects on queued messages and waiting callers, and the resulting state. Only the permission/authorization angle is 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% for the single session_id parameter, and the schema already ties it to run_thronglet. The description adds no syntax or format detail beyond that, 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?

States a specific verb (cancels) and resource (the session's running turn) and even names the underlying operation (session/cancel). It also references siblings wait_thronglet and send_message, so an agent can distinguish this tool's role from theirs 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?

Gives clear context for when the tool matters and explicitly notes the no-op case on an idle session, which prevents pointless calls. It stops short of naming an alternative tool or exclusion for other cancel-like scenarios, so it is not a full when/when-not routing statement.

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 and no output schema, the description carries the full disclosure burden and does well: it reveals that both available and unavailable harnesses are returned, that unavailability comes with a reason, and that server limits are included. It does not explicitly state the operation is read-only, though 'Lists' strongly implies 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?

A single front-loaded sentence with no filler. The purpose and the returned structure are packed into one clean clause.

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, the description adequately explains the return payload, covering available, unavailable, and limit categories. Minor gaps remain about exact format or size of the response, but nothing essential for correct invocation 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no filtering or selection arguments are needed to obtain the full harness list.

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 (Lists) and resource (harnesses), then enumerates exactly what is returned: available harnesses with models and effort levels, unavailable ones with reasons, and server limits. This clearly separates it from siblings like list_thronglets, since it is specifically about agent values consumed by run_thronglet.

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?

By framing the output as the 'valid agent values for run_thronglet,' it implies the tool should be called to discover acceptable inputs before invoking run_thronglet. There is no explicit when-not or named alternative, but the usage context is unambiguous.

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 a good job: it defines the state enum, explains that accepts_messages=false means send_message will fail, and discloses the important caveat that live state belongs to this server while sessions from other throng instances may be stale records. It stops short of stating read-only/non-mutating nature explicitly.

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?

Dense but front-loaded: the verb and scope come first, followed by the returned fields and the freshness caveat. The long field enumeration is justified because there is no output schema to carry it, though it reads as a run-on list.

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, so the description must document return values itself, and it does so field by field, including the error field and cross-instance freshness semantics. An agent has everything needed to call and interpret this zero-param 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 schema to describe and the baseline is 4. No parameter-level ambiguity exists for the agent to resolve.

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 (lists) and resource (thronglet sessions) with a clear scope qualifier ('on this machine'), and enumerates the returned fields. It does not explicitly name the sibling tools it is distinct from, but 'list' versus run/cancel/send/wait 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 rather than stated: the agent can infer this is the discovery/inspection call before acting on a session. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling, so guidance is only 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, the description carries the burden and does so well: it documents both return shapes ({session_id, text, stop_reason, usage, duration_s, warnings?} and the structured variant), the background contract ({session_id, state, queued}), and the 21600s default timeout. It omits side-effect/risk disclosure (the agent executes commands in the user's tree) and failure/timeout behavior, 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-loaded with the core action and return contract, then progressive detail on structured output and background mode. Dense and semicolon-heavy, but nearly every clause carries operational information; the listing-name note is the only mildly incidental 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 7-parameter tool with no output schema and no annotations, the description covers return values for both sync and background modes plus the default timeout, which is what an agent needs to call it. Gaps remain around error/timeout handling and the privilege implications of running an agent in a working tree.

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, but the description adds meaning the schema alone does not: that schema swaps `structured` in place of `text`, that background changes the returned shape and requires wait_thronglet, and that description surfaces the run in session listings. Only `cwd` and `timeout_s` get no added context 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 ('Runs') plus resource ('an agent of an installed harness') and scope ('on a task in cwd'), then distinguishes itself by pointing at list_harnesses for valid agents and wait_thronglet for async collection. An agent can separate this from send_message/cancel_thronglet 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?

Gives clear routing for two cases: fetching valid agents via list_harnesses and retrieving async results via wait_thronglet when background: true. It does not, however, contrast itself with send_message (continuing an existing session) or state when not to launch a new run, so it stops short of full when/when-not coverage.

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 so well: it discloses that turns on one session never overlap, that a message to a busy session blocks until the turn ends, that background mode changes the return shape and requires wait_thronglet to collect, that steer interrupts the running turn and jumps the queue, and that non-resumable sessions reject all messages including steer. These are exactly the traits an agent cannot infer 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?

Dense but front-loaded: the core purpose and the run_thronglet return-equivalence come first, followed by the blocking rule, then background, then steer, then the terminal limitation. Every clause carries information; there is no filler or restatement of the 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 6-parameter mutating tool with nested schema input, no annotations, and no output schema, the description covers the hard parts: concurrency, interrupt semantics, async collection, and the dead-session case. Minor gaps remain — nothing on error/timeout behavior and only a pointer ('same JSON as run_thronglet') for the default return payload — but nothing critical to correct invocation 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 real semantics beyond the schema for two parameters: it explains what background:true actually returns and how to retrieve the result, and clarifies steer's queue-ordering effect relative to pending messages. session_id's provenance is also stated. timeout_s and schema remain schema-only, which keeps this from a 5.

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 ('Sends the next message into an earlier session') and immediately anchors it to the sibling it depends on ('session_id from run_thronglet'), which cleanly separates it from run_thronglet (start a session) and wait_thronglet (collect a result). An agent can pick this over its siblings 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?

Gives explicit conditional guidance: use background:true when you want an early {session_id, state, queued} return and then wait_thronglet, use steer:true when you must interrupt the in-flight turn, and note that sessions showing accepts_messages: false in list_thronglets cannot receive messages at all. It does not spell out the inverse case (when to prefer run_thronglet over this), so it falls just short of fully explicit 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?

With no annotations, the description carries the full burden and does well: it discloses the timeout behavior (returns {session_id, state, queued} instead of an error), idempotency, and that results are persisted with the session. It stops short of auth requirements or rate limits, but the core behavioral 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 dense sentences with zero waste; the primary behavior is front-loaded and the timeout and idempotency caveats follow logically. Every sentence earns its place.

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

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

With no output schema, the description must explain return values, and it does: both the success path (run_thronglet JSON or its error) and the timeout path ({session_id, state, queued}). It leaves the possible 'state' values undefined, but for a wait primitive this 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 coverage is 100%, so both parameters are already documented in the schema, and the description's timeout detail (state returned instead of error) mirrors the schema description rather than adding new meaning. Baseline 3 is appropriate when 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 (waits) and resource (session turn), and explicitly distinguishes itself from run_thronglet by noting it returns 'the same JSON as run_thronglet, or its error'. An agent can tell what this does and how it relates to the sibling 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?

The tie to run_thronglet ('session_id from run_thronglet', 'same JSON as run_thronglet') implies this is used to await a previously started run, but there is no explicit when-to-use or when-not guidance, nor a named alternative (e.g., polling run_thronglet). Usage is inferable but not stated.

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