port_check

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

No annotations exist, yet the description discloses a lot: banner collection is passive, nothing is sent, and filtered means no answer (usually a firewall). It also warns about databases/RDP/telnet exposed to the internet. Not covered are rate limiting or whether the tool needs any authorization, which leaves a small gap for a zero-annotation 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?

Dense, front-loaded prose: the core capability comes first, followed by the port syntax constraint, then the interpretation of states and the safety model. Every clause adds operational information; none 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?

With an output schema present, return-shape explanation is not required, and the description covers the semantics an agent needs for interpretation (open/closed/filtered, banners, risk warnings). The unexplained `timeout_s` is the only meaningful omission for a 3-parameter 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?

Schema description coverage is 0%, so the description must carry the parameters. It fully specifies the `ports` syntax and its 20-port ceiling, and implies `host` is a single host, but `timeout_s` is never mentioned, so one of three parameters is undocumented 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?

Uses a specific verb-plus-resource formulation: checks TCP port reachability on one host and captures banners. It also implicitly separates itself from http_check/tls_check by framing the job as raw port state (open/closed/filtered) rather than protocol-level checks.

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 scope limits: max 20 ports per call, health check rather than scanner, CIDR ranges refused. That tells the agent when this tool is inappropriate, but it never names a sibling (e.g. http_check or tls_check) as the alternative when a protocol-level probe is wanted.

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