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

Goes well beyond the annotations by disclosing the exclusivity model, the refusal condition ('refused while another live session holds it'), and all three ways a claim ends, including the 15-minute idle expiry and MCP process exit. This is exactly the lifecycle and contention context annotations cannot express.

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 compact sentences, front-loaded with the action, then the reason, then the constraints. No repetition of the name or 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 no explanation, and the contention/expiry semantics are fully covered. The remaining hole is the meaning and sourcing of the 'session' argument, which matters for a tool whose whole purpose is binding a specific session.

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 required 'session' parameter has 0% schema description coverage, and the description never says what a session identifier looks like or where to obtain it (presumably from list_terminal_sessions). The phrase 'this session' is about the caller, not the parameter, so the gap is left unaddressed.

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 ('Claim a Termius tab for this session') and immediately ties it to the run_command/send_key/send_text family, which no other sibling does. An agent can distinguish it from release_terminal or switch_terminal 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?

Explains the precondition that makes the tool necessary (the command tools refuse unclaimed tabs) and gives a preference rule ('prefer a tab of your own over one a human or another agent is using'). It names release_terminal as the exit path but doesn't spell out when to claim versus simply calling switch_terminal.

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 beyond the destructiveHint/readOnlyHint annotations by naming the concrete safety default (refuses busy or non-prompt sessions) and the concrete cost of force ('can interrupt work'). It also instructs verification of actual removal rather than trusting dispatch, which is real behavioral context an agent needs before invoking a destructive 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?

Four short sentences, front-loaded with the core action and scope, followed by the force caveat and a verification note. No filler and no repetition of the annotations.

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 an output schema present and annotations declaring the destructive profile, the description only needs to add operational nuance, which it does for force and scope. The remaining gap is the session parameter and any hint about how to distinguish close from release among 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 description coverage is 0%, so the description must carry the load: it does so thoroughly for force, explaining its default-refusal semantics and the interrupt risk. It says nothing about session (format, provenance from list_terminal_sessions/claim_terminal), leaving one of two params undocumented, though the name is fairly self-evident.

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 (close) and resource (one claimed terminal session) and immediately bounds scope with 'never the whole app', so an agent knows this affects a single session. It does not differentiate from the closely related sibling release_terminal, which an agent could reasonably confuse with closing.

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

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

Explicit when/when-not guidance for the dangerous path: default refuses busy/non-prompt terminals, and force=true 'use only when the user explicitly requests that'. It lacks routing guidance to alternatives such as release_terminal or switch_terminal, but the conditional usage for force is unusually clear.

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

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

Goes well past annotations: discloses tab reuse/claim semantics, that a claimed tab is never taken and the error names the holder, that credential/key/jump host handling is delegated to Termius with no credential read or passed, host-key prompt policy via TERMIUS_HOSTKEY (changed keys never accepted), and that password prompts are refused and must be handled by reading the terminal and asking the human. This is substantive behavioral context annotations cannot express.

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 core behavior in the first sentence and then layers constraints, with no filler sentences. Density is high — capital-letter emphasis and stacked parentheticals make it heavier than needed — but each clause carries distinct 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?

Covers prompts, credential policy, allow-listing, and failure modes for a mutating open-world tool; return values need not be explained because an output schema exists. The one gap is the undocumented `wait` parameter, which affects call timing.

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 0%, so the description must compensate. It does for three of four parameters — host (exact label from list_hosts), new_tab (always opens a new tab), dry_run (only checks host and connect function) — but `wait` (default 30) is never mentioned, leaving its unit and effect undocumented.

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 ("Get a tab for a SAVED Termius host") and pins the host argument to "exact label from list_hosts", which separates it from the list_* siblings. An agent can distinguish this from claim_terminal or switch_terminal 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?

Explicitly defines when a tab is reused vs newly opened, states that human/other-session tabs are never reused implicitly, that new_tab=true always opens fresh, that another session's claim causes failure, and that dry_run only validates host + connect function. TERMIUS_CONNECT_ALLOW restriction is also disclosed — a full when/when-not set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed world, so safety is covered. The description adds genuinely new behavioral context that annotations cannot: credentials (passwords and keys) are deliberately excluded from the output, which tells an agent it cannot chain directly into an authenticated call from this data. Pagination, ordering, and result limits remain unstated.

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 compact sentences with no filler. The returned-field list leads, the security caveat follows, and the parameter note closes — a sensible front-loaded order with every clause carrying 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?

An output schema exists, so return-structure explanation is not required, yet the description still signals the shape of a result and the privacy constraint on it. For a single-optional-parameter read tool with strong annotations, this is close to complete; only edge behavior (empty results, large host lists) 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 0%, so the description must carry the parameter burden, and it does: it explains that `query` filters by label, address, or group, which is information the bare string/null schema does not convey. It stops short of specifying match semantics (substring vs. exact, case sensitivity) or that null means no filtering.

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 ('List saved Termius hosts') and enumerates the returned fields (label, address, port, group, username, auth type), which distinguishes it from the session-oriented siblings like list_terminal_sessions and list_sftp_sessions. It never explicitly contrasts itself with connect_host, so differentiation is left partly 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?

Usage is implied rather than stated: an agent can infer this is the discovery step before connect_host or a key-based action, but no sentence says when to use this versus those alternatives or what prerequisites exist. No exclusions or negative conditions are given.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: the SFTP-view prerequisite and the guarantee that no credentials are returned, which matters for an agent handling secrets.

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 clauses, no filler, and the core purpose leads. Each sentence adds distinct information: what is listed, the prerequisite, and the return-value guarantee.

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 no-parameter, read-only listing with full annotation coverage, the description covers purpose, prerequisite and a key return-value caveat. It lacks an output schema and only partially sketches the return shape, but nothing needed to invoke the tool 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies a no-argument call by not referencing any inputs.

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 ('currently connected SFTP panes') and enumerates the returned fields (session ID, host, directory). This clearly separates it from list_terminal_sessions and sftp_transfer_status, 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?

Gives a concrete precondition: 'Open Termius' SFTP view first', which tells the agent exactly what state must exist before calling. It stops short of stating when to prefer this over alternatives or when not to use it, so it falls just short of the top band.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's real addition is the `session` handoff convention, but it says nothing about ordering, whether results span windows/workspaces, or freshness of connection state — modest value on top of structured fields.

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, no filler. The resource and scope are front-loaded, and the cross-tool identifier note follows 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?

With an output schema present, the description need not explain return values, and the enumerated fields are a reasonable hint. It is nearly complete, but an agent still cannot tell whether the list is scoped to a window/workspace or how large it might be.

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, which is the baseline-4 case. The description correctly offers no parameter guidance and instead explains how the values this tool returns are consumed as `session` elsewhere.

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 terminal sessions open in Termius") and narrows the scope to SSH and local tabs, which implicitly separates it from list_sftp_sessions and list_hosts. It stops short of naming the sibling it is not, so an agent must infer the boundary rather than read it.

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 second sentence gives concrete downstream guidance: any of id prefix / name / address can be passed as `session` to the other tools, which tells the agent to call this first to obtain an identifier. There is no explicit when-not or a named alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral value: output is ANSI-stripped, blank runs collapsed, and scrollback is capped – though the cap is not quantified. It omits what happens when `session` is null or invalid.

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 clauses, zero filler, with the output transformation front-loaded and the default behavior stated before the alternate mode. Every sentence 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?

An output schema exists, so return-value documentation is not required, and the description covers mode selection and output normalization adequately. The remaining gap is the unexplained `session` parameter, which matters in a multi-session toolset.

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 0%, so the description must carry parameter meaning. It does explain `lines` (tail of the screen) and `scrollback` (full history, capped), but `session` — the parameter an agent most needs given many terminal siblings — is entirely unexplained in both schema and description.

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 terminal text') plus transformation details (ANSI stripped, blank runs collapsed). It is implicitly distinguishable from write-side siblings like send_text and run_command, but it never names them, so the differentiation is inferred rather than stated.

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 explains the two read modes (default screen tail vs scrollback history) and which flag selects each, which is useful usage guidance. It gives no guidance on when to use this versus list_terminal_sessions or run_command, and no mention that `session` selects among terminals.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the ownership framing ('a tab this session claimed') but never says what release actually does to the tab — whether it stays open, becomes claimable by others, or invalidates later read_terminal/send_text calls.

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 the ownership constraint. There is mild redundancy between 'Release a tab' and 'Release when…', but nothing that wastes real space.

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 no explanation, and annotations cover safety and idempotency. The remaining gap is lifecycle semantics — what state the tab ends up in after release and how that interacts with close_terminal — which matters for a tool sitting in a claim/release/close family.

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 0% for the single 'session' parameter, so the description has to carry it. The phrase 'this session claimed' does imply the parameter is the caller's session identifier rather than an arbitrary tab ID, which is a meaningful clarification, but no format or validation detail is given.

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 ('Release') and resource ('a tab this session claimed'), and the ownership qualifier implicitly separates it from sibling 'claim_terminal'. It is not as crisp as naming the sibling outright, but an agent can tell what it does.

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?

'Release when your work on the tab is done' gives a when-to-use condition, but there is no when-not, no mention of claim_terminal as the counterpart, and no indication of whether release is mandatory before close_terminal or further claims by 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?

Goes well beyond the destructive/openWorld annotations: it discloses that the call blocks until the prompt returns, that output is post-processed (echo and prompt removed), and exactly what comes back on timeout. The claim_terminal ownership requirement is a real behavioral constraint an agent must know before calling.

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 action and result contract, then the timeout branch, then the prerequisite. No filler and nothing requiring a second read.

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 described, and annotations already flag the destructive/open-world nature. The only real gap is the unexplained `session` parameter and no note on what permissions or host-side state the command runs under.

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 0%, so the description carries the burden. It explains timeout behavior well (partial output plus a status line when still running or waiting for input) and implies what `command` is, but the `session` parameter is never explained (default null, presumably the claimed/current session).

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 ('EXECUTE a shell command on the remote host') plus the execution model (waits for prompt, returns only command output with echo and prompt stripped). This clearly separates it from sibling primitives like send_text, send_key, and read_terminal, which do not wait for completion or return cleaned 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 an explicit precondition ('The tab must be claimed by this session first (claim_terminal)') and routes the timeout case to specific alternatives ('use read_terminal / send_key("ctrl-c") to follow up'). It stops short of saying when to prefer send_text/read_terminal over run_command for genuinely interactive programs, so not a full when/when-not 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?

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral fact ('enter' submits whatever is typed), but says nothing about session targeting, focus, or what a destructive key press does to running processes.

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?

Compact and front-loaded: the verb and resource lead, the key list follows, and the one behavioral caveat is last. The long enumeration is justified by the absence of a schema enum, though it makes the sentence slightly list-heavy.

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 explained. However, for a destructive, open-world tool with an undocumented session parameter, the description is incomplete: it never explains session scoping or what 'enter' submitting text means for the terminal state.

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 0%, so the description must carry the parameter burden. It does compensate for the missing enum by listing valid key values, but it completely ignores the 'session' parameter and doesn't explain whether 'key' is case-sensitive or how the session is resolved.

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 one control key') and enumerates the exact key set, which is more precise than the vague schema. It implicitly distinguishes itself from send_text by the word 'one' and 'control key', but never names that sibling 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 explicit guidance on when to use this instead of send_text or run_command, which are both plausible alternatives for terminal interaction. The note about 'enter' is behavioral, not routing guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds the reason worth heeding — a foreground program may act on any input — which is real risk context an agent can't infer from the hints. It stops short of explaining session targeting or what happens if the text contains control characters.

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

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

Two sentences, front-loaded with the core behavior and followed by the risk note and alternatives. No filler, and the most important constraint comes first.

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?

Annotations and an output schema cover safety and return shape, and the submit-vs-execute guidance is present. However, for a mutation tool that writes into a live session, the absence of any statement about which session is targeted and how non-printable input is handled leaves a meaningful 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 coverage is 0%, so the description carries the full burden, yet the 'session' parameter is never mentioned and it is unclear which terminal receives the text by default. Only the 'text' parameter is indirectly characterized as 'printable text without Enter'.

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 printable text) and immediately scopes it with 'without Enter', which is the defining distinction from send_key. It also names the two siblings an agent might confuse it with, so selection is unambiguous without opening 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 concrete routing: use send_key('enter') to submit, or run_command to execute and collect output. That covers the main alternatives, though it doesn't address when to prefer this over switching/claiming a different terminal session first.

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 establish read-only, non-destructive, closed-world behavior. The description adds meaningful context beyond that by clarifying that status data is retained and that apparent completion signals can be misleading.

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 core operation and followed by the most important interpretation caveat. There is no wasted wording.

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 read-only status tool, the description covers the core purpose and the key pitfall about interpreting progress. It leaves minor gaps around transfer ID provenance and exact return fields, but remains largely sufficient.

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 0% schema description coverage, so the description must carry the explanatory burden. It says only 'by transfer ID,' which adds little beyond the schema property name and does not explain where the transfer ID comes from or what format it takes.

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: reading retained native upload progress, errors, or completion by transfer ID. It is clearly distinct from sftp_upload and list_sftp_sessions, though it does not explicitly name 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?

The intended use is implied: check upload status using a transfer ID. The caveat that 100% progress or a disappeared queue row does not mean completion is useful guidance, but the description never explicitly says when to call this versus other SFTP lifecycle tools.

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 destructive/openWorld, but the description adds material behavior the agent cannot infer: overwrite dialogs are left for the human and this tool never approves them, timeout does not cancel the transfer, and credential stores (~/.ssh, ~/.aws, keychains) are refused, with TERMIUS_UPLOAD_ROOTS able to further narrow allowed directories. That is exactly the kind of failure-mode and policy context annotations cannot express.

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 in sentence one, and each subsequent sentence carries distinct operational information — no filler or restatement. The prose is dense and slightly run-on (parenthetical examples, UI pane instructions crammed mid-paragraph), which costs a bit of scannability.

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 transfer with no output schema, the description covers prerequisites, refusal policy, dialog handling, and timeout recovery, and it implies the return value ('the returned ID') that feeds sftp_transfer_status. It stops short of describing the transfer result shape or how end/error events surface to the caller, a minor gap given no output schema exists.

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 0% schema description coverage the description must carry all four parameters, and it does most of the work: sftp_session is tied to list_sftp_sessions, remote_directory is tied to the pane navigation step, and local_path is constrained to a single regular file. The timeout parameter is only obliquely addressed ('Timeout does NOT cancel') with no unit or what stage it bounds, leaving one gap.

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 first sentence gives a specific verb and resource — 'Upload one local regular file through Termius' native SFTP transfer queue' — including the cardinality constraint (one file) and the transport used. It is immediately distinguishable from siblings like sftp_transfer_status (status polling) and list_sftp_sessions (session discovery), both of which it names.

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 prerequisites and routing are given: use the exact session ID from list_sftp_sessions, set one pane to Local, and navigate the remote pane to remote_directory first. It also states the critical when-not: on timeout do not blindly re-upload, follow sftp_transfer_status with the returned ID instead.

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, openWorldHint=true, and destructiveHint=true. The description adds useful behavior by noting that the containing tab is activated and state is verified, but it does not explain the destructive implication flagged by the annotations or any side effects/permission requirements.

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 description is a single compact sentence with the action front-loaded and no redundant text. Every phrase contributes to the core behavior.

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?

Although an output schema exists and annotations supply safety hints, the description is incomplete for a mutation tool with destructiveHint=true and openWorldHint=true. It says nothing about what is destroyed or changed beyond focus activation, invalid-session behavior, or permissions.

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 0%, and the sole parameter "session" is undocumented beyond its title. The description implies that the session corresponds to an explicitly selected terminal, but it adds no format, identifier, or constraint details needed to populate the parameter correctly.

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 uses a specific verb ("Activate") and resource ("terminal and its containing tab"), making the action clear. It does not explicitly differentiate from sibling tools such as claim_terminal or read_terminal, so it stops short of a 5.

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 phrase "explicitly selected terminal" gives a minimal selection condition, but the description does not state when to use this tool versus alternatives like claim_terminal, read_terminal, or list_terminal_sessions. 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.