Add a request-modification rule

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that this is an interception tool that modifies requests before forwarding to the real backend, which implies a live-traffic side effect distinct from pure mocks. It covers the key modification dimensions (headers, query, body). However, it doesn't disclose whether rules are additive, whether existing matching rules get overwritten, or any persistence behavior.

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 two sentences with zero waste. The first sentence states the purpose and flow, the second provides practical parameter usage guidance. Every word contributes value.

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 an 8-parameter tool with nested objects and no output schema, the description is reasonably complete—it explains the core flow (intercept, modify, forward, return) and how to use the major parameter groups. However, it doesn't explain the URL matching semantics (glob/substring vs regex) beyond what the schema already states, nor does it clarify edge cases like whether removing and setting a header in the same rule is supported. Given that schema covers all parameters, this is adequate.

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 100%, so all 8 parameters are documented in the schema. The description adds meaningful value by grouping parameters into functional categories (setHeaders/removeHeaders for headers, setQuery/removeQuery for URL params, body for body replacement), which is helpful orientation beyond the schema's individual descriptions. This exceeds the baseline 3 for full coverage.

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 intercepts and modifies requests: 'Intercept a request matching method+URL, modify it (headers, query params, body), forward to the real backend, and return the response.' It uses specific verbs (intercept, modify, forward) and explicitly lists the resources being modified. It distinguishes from sibling mock tools by framing this as request modification with real backend forwarding, though it doesn't explicitly name the distinguishing sibling.

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 clear operational guidance on how to use the tool: 'Use setHeaders/removeHeaders to modify headers, setQuery/removeQuery for URL params, and body to replace the request body.' This effectively explains which parameters to use for each modification type. However, it does not explicitly state when NOT to use this tool versus alternatives like proxy_mock_transform or proxy_mock_response, though the context implies this is for real-traffic interception rather than canned mock responses.

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