reverse_port

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

With no annotations, the description carries the full behavioral burden. It explains the mechanism (device-localhost traffic tunnels to the host), which is genuinely useful, but says nothing about persistence across reconnects, conflict behavior with existing reverses, or that a mapping is added to state that must later be removed. The mechanism is clear; the side effects are not.

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 dense sentence, front-loaded with the command form and immediately followed by the directional explanation and an example. Nothing is wasted and the key distinguishing information comes first.

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 return values need no explanation, but with zero schema coverage and zero annotations, the description should do more: the serial parameter is undocumented and stateful consequences (persistence, removal via remove_reverse) are unmentioned. It covers purpose and direction adequately but leaves real gaps for a mutation 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 coverage is 0%, so the description must compensate. The adb command form and the '127.0.0.1:<device_port>' example clarify the roles of device_port and host_port, but the third parameter (serial) is entirely unaddressed and no type/format guidance is given, so the coverage gap is only partially filled.

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 gives a precise verb+resource with directionality: it maps a DEVICE port to a HOST port, distinguishing it semantically from forward_port by stating which side each port lives on. It does not name the sibling alternative explicitly, so an agent must infer the forward/reverse distinction, keeping it just below a 5.

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?

A concrete use case is provided ('so the app's 127.0.0.1:<device_port> traffic reaches your PC, e.g. a local API/CDN shim'), which implies when to reach for it. However, there is no explicit when-not guidance and no reference to forward_port or the remove_reverse/list_reverses siblings, leaving the usage context only implied.

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