proxy_guidance

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

With only readOnlyHint=true in annotations, the description should carry heavy behavioral burden and it does: it discloses that nothing is written, no listener starts, request scanning vs. response streaming behavior, refusal of unparseable governed bodies, and the critical chokepoint-vs-enforcement caveat. This goes well beyond the annotation's safety hint.

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 front-loaded with the key [READ]/WRITES NOTHING framing and organized into clear paragraphs. It is slightly verbose in places but every sentence adds meaningful caveats or behavioral detail rather than restating 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?

Given no output schema, no annotations beyond readOnlyHint, and 0% schema description coverage, the description supplies the missing context: what the tool does not do, what it returns (the caveat), how the proxy behaves, and parameter meanings. An agent has enough to invoke and interpret it correctly.

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 explain parameters. It documents listen_host, listen_port (with default 11435), and target semantics reasonably, though listen_host's default (127.0.0.1) is omitted and format expectations are not fully specified.

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 opens with a specific verb+resource ([READ] How to run the transparent capture proxy) and immediately differentiates itself from siblings by clarifying it WRITES NOTHING and starts no listener. An agent can tell this is a guidance/composition tool rather than an execution tool without checking the schema.

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?

It clearly frames the guidance context ('how to run... and what it does NOT guarantee') and explains the composition behavior, but does not explicitly name alternative sibling tools or state precise when-not-to-use conditions (e.g., when to use running_models or server_status instead).

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