status

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

With no annotations provided, the description carries full behavioral burden and largely succeeds: it discloses the comprehensive read-only scope across ALL open ports, the specific state domains covered, and the empty-state behavior. It stops short of explicitly confirming non-mutation or data freshness, but the verb 'Report' plus the disclosed edge case gives solid coverage for a status 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?

Two sentences with zero waste. The core verb-action is front-loaded ('Report every open port'), the content enumeration is compact yet informative, and the edge-case sentence earns its place by covering the nothing-open scenario. Every clause adds 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?

Complete for a no-argument diagnostic tool. Zero parameters remove the parameter-documentation burden, an output schema exists to cover return values, and the description handles every remaining question an agent could have: what is reported, over what scope, and what happens with no open ports. Nothing an agent needs to invoke it 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?

Zero parameters, so the baseline is 4. The description reinforces the no-argument global-report nature ('every open port') consistent with the empty input schema, and adds that no target/port selection is needed. There is nothing more the description could meaningfully add about parameters that do not exist.

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?

Specific verb 'Report' plus resource 'every open port', followed by an enumerated list of content categories (settings, reader state, buffered bytes, control-line states, capture, current connection). The second sentence adds scope precision by describing the no-connection case. This clearly differentiates it from siblings like list_serial_ports (hardware discovery), connect/disconnect (lifecycle changes), and read_available (data reading) — it is unambiguously the connection-state reporting tool.

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 diagnostic use case is implied rather than stated: 'Report every open port' signals this is the tool to call when you need current connection state, and the edge-case sentence tells the agent it still returns useful information when nothing is open. However, among 29 siblings, the description never explicitly names alternatives (e.g., screen, read_available, port_in_use_by) or states when NOT to use it, so routing is left to inference.

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