connect_host

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.