Agenterm

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

Beyond the annotations, the description discloses the 15-minute invitation lifetime, single-use versus reusable invitation semantics, polling behavior with list_clients, and the fact that tokens and commands are credentials to be shared privately. It also states that invitation creation alone does not complete the task and that the agent must actually call list_clients rather than merely saying it is waiting.

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 purpose is front-loaded, but the description is quite long and contains repeated workflow warnings, such as 'Do not end the turn' and 'Saying you are waiting is insufficient,' plus a tangential note about session_id. The complexity partly justifies the length, but it could be tightened without losing required guidance.

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

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

For a tool with a defined workflow and an output schema, the description is complete enough to call and operate correctly: it explains creation semantics, the required progress message, the polling loop, notification timing, and credential handling. The output schema can cover return structure, so the description does not need to duplicate 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 single parameter has 100% schema description coverage, and the description largely restates the schema’s explanation of multi_device. It does not add syntax or edge-case detail for that parameter beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Create a client connection token and a 15-minute invitation.' It also clarifies the multi_device behavior and contrasts the client-token workflow with session tools that use session_id, making the tool’s role clear relative to 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?

It gives explicit conditions for multi_device=true versus the default single-use/single-device case, then prescribes the follow-up sequence: show display_text, call list_clients repeatedly with client_token and wait_ms=20000, and continue until a device connects, the invitation expires, or the user cancels. It also warns not to end the turn after showing the invitation or an empty result.

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 annotations: warns that commands can modify/delete files and require user approval for destructive ones, that each call starts a fresh shell with no persistence, documents timeout defaults/limits, the 1 MiB shared stdout/stderr cap with truncation, the result field set, error semantics, and that cancellation is best-effort and does not undo effects. These are real operational constraints an agent cannot infer from destructiveHint/openWorldHint alone.

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

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

Front-loads the purpose and danger warning, then proceeds through auth, shell semantics, timeout, output limits and result shape. Dense but well ordered; the result-field enumeration is borderline verbose given an output schema exists, which costs a point.

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

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

Covers everything an agent needs for a destructive, open-world, non-idempotent tool: approval guidance, auth requirements per token type, non-persistence of shell state, timeout bounds, output truncation, error signaling, cancellation limits, no retry, and sibling routing. The output schema's existence makes the brief result listing sufficient rather than redundant.

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 coverage the baseline is 3, but the description adds cross-parameter meaning: client_token is required with management access (including stdio/no-password mode), client_id is required for multi-device tokens, and cwd/env must be set per call because shells are fresh. These reinforce and contextualize the schema rather than merely restating it.

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

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

States a specific verb+resource ('Run a non-interactive shell command') plus the scope ('on the selected authorized target device and wait for completion'). It explicitly distinguishes itself from the session_* siblings by naming them as the alternative for prompts, incremental output and long-running jobs.

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 last sentence explicitly routes agents to session_start/read/write/stop for interactive or long-running scenarios, which is a clear use-vs-alternative rule. It gives no explicit exclusions for execute_command itself beyond the 'non-interactive' framing, so it falls short of a full when/when-not treatment.

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 read-only, idempotent, non-destructive, closed-world, so the safety bar is met. The description then adds non-obvious behavior: long-poll semantics, the fact that an empty result means timeout rather than no devices, and that notification should fire on connect. This is real added context beyond the annotations, though it does not cover limit/output shape (an output schema exists).

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

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

Front-loaded with the purpose, then the wait/snapshot distinction, then the workflow loop. Nearly every sentence carries operational instruction. It runs long and partially restates the wait_ms schema text, which keeps it from a 5.

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

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

An output schema exists, so return-value documentation is not required. Given a 2-parameter long-poll tool, the description covers purpose, polling cadence, empty-result interpretation, termination conditions, and the follow-up tool — everything an agent needs to call it correctly inside a multi-turn flow.

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 goes further by explaining the polling loop pattern for wait_ms and its interaction with invitation expiry, and by noting that for multi-device tokens any online device completes the wait. The client_token access-model caveat is left to 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?

Opens with a specific verb and resource: 'List online devices belonging to this client_token.' It is immediately distinguishable from siblings like create_client, execute_command, and session_start, and the scope (online devices only, scoped by token) is explicit.

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

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

Gives explicit branching guidance: use wait_ms=20000 to block after creating an invitation, omit or use 0 for an immediate snapshot. It also states what to do on an empty result (keep waiting, do not end the turn) and names the downstream handoff ('Use client_id to execute commands or start sessions'), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior well beyond them: 1 MiB buffer truncation with truncated=true, cursors as byte offsets, out-of-range cursor is an error, done=true gating which fields appear, and that a disconnect error is not proof of success or confirmed cancellation. Lifecycle constraints (30-minute expiry, restart invalidation) are also disclosed.

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

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

Dense but essentially waste-free, and front-loaded with the purpose and the negative boundary before the cursor/wait mechanics. It is a long single paragraph, so the polling, truncation, and expiry rules run together; light structuring would make it easier to scan, but no sentence is filler.

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

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

An output schema exists, so return values need not be enumerated, yet the description still explains when exit_code/timed_out/canceled/error appear. For a 4-parameter, stateful read tool with cursor and timeout subtleties, everything needed to call it correctly and interpret edge cases is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: cursor is a byte offset not a character count, must start at 0 and be chained from next_cursor, and an over-range cursor errors. wait_ms gains the 0-20000 range, default 0, and the semantic distinction between immediate return and waiting for new output or a terminal state.

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 ('Read incremental output and terminal state for an owned session') and immediately draws the boundary against siblings: 'This does not send input or stop the process.' An agent can distinguish it from session_write and session_stop without inspecting 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?

Explicit invocation protocol: 'Start with cursor=0, then use the returned next_cursor on each read', plus the polling rule ('Empty output with done=false is only a polling timeout; continue polling'). It also names the alternatives and when to use them: 'Use session_stop to terminate and session_write to supply input.'

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 flag destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is largely covered, but the description still adds real context: the return is session_id plus cursor 0 rather than command completion, repeated calls fork separate processes, six sessions per token, only the latest 1 MiB retained, 30-minute expiry, and server restarts invalidate sessions. That is substantive beyond annotations, though pagination/streaming mechanics remain implied rather than spelled out.

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 permission implication, then lifecycle and constraint details in a logical order. Some sentences restate schema-level facts (timeout_ms default/max, cwd/env) that could be trimmed without losing meaning.

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

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

For a destructive, open-world, stateful tool, the description covers lifecycle (read/write/stop), resource limits (six sessions, 1 MiB buffer), expiry, and restart invalidation. With an output schema present, it need not specify return field shapes, so nothing critical 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 schema already documents command, client_id, cwd, env, timeout_ms, and client_token with the same details the description repeats (multi-device client_id requirement, timeout default of 0 with 24h cap). The description adds only light cross-parameter workflow framing (cwd/env apply to this new process) and does not compensate with anything the schema lacks, 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 ("Start a new interactive terminal process") plus a scope qualifier ("authorized target device"). The closing sentence explicitly contrasts it with execute_command for non-interactive commands, so an agent can distinguish it from the closest sibling without opening either 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 routes the agent across the whole workflow: session_read with next_cursor to collect output until done=true, session_write to answer prompts with a newline, session_stop to cancel, and execute_command for short non-interactive commands. Both the when-to-use and the when-to-use-something-else conditions are stated.

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

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

Although annotations already flag destructive/idempotent/non-readOnly, the description adds substantial context they cannot convey: stopping can interrupt writes and lose unsaved work, side effects are irreversible, accepted=true only means a request was sent or pending, and status=stopping/done=false requires polling. It also spells out the already_done=true/accepted=false repeat-call behavior, which directly explains the idempotentHint.

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

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

Front-loaded with purpose, then requirements, risks, wait_ms behavior, and status semantics in a logical order. It is dense but long, and the wait_ms explanation partially duplicates the schema property description, costing a bit of efficiency.

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

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

For a destructive, open-world mutation tool this covers everything an agent needs: preconditions, side-effect risk, timeout behavior, the meaning of each status/accepted combination, and the required follow-up call. Even though an output schema exists, the description adds interpretive value about status transitions rather than restating field shapes.

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 goes further by explaining the ownership rule for client_token ('cannot stop a session owned by another token') and the wait_ms trade-off between 0 and a blocking wait. These are semantic consequences not derivable from the schema's type/range constraints.

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

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

Opens with a specific verb+resource ('Request termination of a terminal session') and ties it to the sibling that creates such sessions (session_start). It also implicitly separates itself from session_read and session_write by stating their roles at the end, so an agent can place it precisely among the six 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?

Explicitly states when it applies (session created by session_start, owned by the calling token), when it will fail (unknown/unauthorized IDs, sessions owned by another token), and how to retry ('Repeating a stop is safe'). It routes the agent to session_read for polling and session_write for input, and clarifies it does not revoke tokens or disconnect other sessions.

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

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

Adds substantial context beyond the destructive/non-idempotent annotations: that input can trigger destructive operations, that input may be echoed in output including secrets, that repeating a write resends input, and that unknown/ended sessions error. The key disclosure that accepted=true only means the input reached the device connection, not that the program consumed it, is genuinely useful and not derivable from annotations.

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

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

Long but front-loaded: the core action comes first, then caveats, then lifecycle exclusions. Nearly every sentence carries a distinct rule, though the secrets/echo warning and the accepted=true caveat could be tightened slightly.

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?

An output schema exists, yet the description still clarifies what the accepted flag does and does not confirm, and covers authorization, error conditions, and follow-up reads. Nothing an agent needs before calling this destructive tool 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. The description still adds real semantics by explaining that a newline is what submits a command or answer, which is behavioral meaning the schema's 'Input bytes as text, e.g. yes\n' only implies.

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: send text to the stdin of an owned running terminal session. It also fences itself off from siblings by naming session_start and session_stop and by pointing to session_read for observing output.

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

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

Gives explicit routing: use session_read afterward to observe the response, and use session_start/session_stop for lifecycle operations since this tool does not start or cancel a session. It even covers the retry case ('do not retry blindly') and the error case for unknown or ended sessions.

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