Start Proxy

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

There are no annotations, so the description carries the behavioral burden. It discloses key behaviors: transparent pass-through, bidirectional frame recording, no frame rewriting, diagnostic-only purpose, and OS-assigned port when listen_port=0. It could add lifecycle details such as needing stop_proxy, but the current level of transparency is strong.

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 description is concise and front-loaded with the core purpose, then adds usage context, protocol constraints, and a behavioral guarantee. The text is slightly dense with wrapping, but every sentence contributes useful information without padding.

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?

The description covers the tool's role, supported protocols, port allocation behavior, and the intended diagnostic workflow. It does not explain all parameters or explicitly mention proxy shutdown, but the output schema and the sibling stop_proxy help fill the remaining context. Overall it is sufficiently complete for correct invocation.

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 compensate for undocumented parameters. It explains protocol values and listen_port=0 behavior, but does not explain target_host, target_port, listen_host, or idle_timeout_sec, leaving significant param semantics to inference.

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 clearly states the tool's function: start a transparent proxy between a host and a real PLC, forwarding frames and recording bidirectional traffic by protocol framing. It distinguishes itself from siblings by emphasizing the diagnostic role and referencing get_proxy_frames, parse_frame, and diagnose for the workflow.

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 description gives explicit usage context: during on-site commissioning, point the host at this proxy instead of the PLC to capture all frames and analyze them later. It also states protocol support limits (modbus/fins/melsec, no S7 TPKT framing), though it does not explicitly contrast with alternatives like start_listener or stop_proxy.

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