Check TCP port

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

Annotations already declare readOnlyHint=true, so the description only needs to add behavioral context; it does state that the check originates from this machine and targets TCP. It does not explain timeout behavior or the exact meaning of 'reachable', but output schema likely covers return values, keeping this at an adequate 3.

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?

A single sentence that is front-loaded with the core action, resource, and scope. There is no filler or repetition of the schema.

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 connectivity probe with an output schema and a read-only annotation, the description covers the key input context (host, TCP port, local origin). It is slightly incomplete regarding how timeout_seconds behaves and whether 'reachable' means successful TCP connection, but the schema and output schema would carry most of that.

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 should compensate by explaining the parameters. It does not; host, port, and timeout_seconds rely entirely on their schema property names. The description adds no semantics beyond restating that a host and TCP port are involved.

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 ('Test whether') with a clear resource ('a TCP port on a host') and adds a useful scope qualifier ('from this machine'). It is clear on its own, but it does not explicitly differentiate itself from sibling tools like port_check or diagnose, so it misses the last bit of distinction.

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?

No guidance is given about when to choose network_check over alternatives such as port_check, port_owner, or diagnose. The description implies a connectivity-check use case but provides no exclusions or decision criteria, so an agent must guess which sibling is appropriate.

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