check_tcp_connect

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

With no annotations, the description carries the full burden and does most of it: it discloses that the check runs over SSH on a remote machine, that only a connection is opened and closed with no data sent, the 3-second timeout, and the exit code 127 case when nc is absent. It stops short of describing authentication behavior (password vs key_path) or what accept_new_hostkey does security-wise.

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 content is front-loaded with purpose before parameter guidance and return-code semantics, and each block serves a purpose. It is long, and the multi-line error taxonomy could be tightened, but nothing is clearly wasteful for a tool with this many failure modes.

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 the ok=True explanation is a bonus rather than a requirement, and the failure-mode taxonomy is genuinely useful. However, for a tool requiring an SSH session, the absence of any guidance on credentials (password vs key_path), the timeout parameter, and host key acceptance leaves an agent without what it needs to construct a successful call in restrictive environments.

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% across 9 parameters. The description compensates well for target_host, target_port, host, port and user (via the SSH framing), but user, timeout, key_path, password and accept_new_hostkey get no explanation at all, leaving roughly half the parameters 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?

The description opens with a precise verb and resource (check whether a TCP connection can be opened from a remote Linux host via SSH) and explicitly scopes it ('nc -vz', 'one port per call'). It also draws the crucial distinction between target_host/target_port and host/port, which an agent could not infer from the names alone.

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 selection rule: 'USE THIS TOOL to tell whether a service (database, API, another server) is reachable from that host,' and routes DNS failures to get_dns_lookup. What is missing is any statement of when not to use it (e.g., checking a local port, or probing service health rather than mere reachability).

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