proxypilot

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds useful override semantics: matching requests get content instead of or on top of the server answer via mode=body_only, and the mapping expires after ttl (default 1h). It does not cover persistence, matching precedence, or conflicts with existing maps, leaving a gap for a destructive mutation tool.

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?

Two sentences, front-loaded with the core effect and then the expiry constraint. Efficient, but 'Mock responses' as an opening noun phrase is slightly less scannable than a direct action statement.

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 11-parameter, destructive mutation tool with no output schema, the description is thin. It explains override and TTL behavior but omits persistence, matching/ordering rules, conflict handling, and how the local map relates to remove_rule or add_map_remote.

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 64%, and the description adds meaning for mode ('on top of' vs 'instead of') and ttl (default 1h), which the enum/default alone don't explain. However, it does not touch url wildcards, body/file exclusivity, headers, methods, or graphql_operation, so several parameters remain undocumented outside the schema.

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 explains the effect of a mock mapping ('matching requests get this content instead of... the server's answer') but never frames the tool as 'add a local mock map' and does not distinguish it from the sibling add_map_remote. The purpose is inferable but not stated with a clear verb+resource.

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?

There is no guidance on when to use this tool versus add_map_remote, add_rewrite, or other siblings, and no prerequisites or exclusions are mentioned. The only implied usage is broad ('mock responses').

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotent=false, so the safety profile is covered. The description adds nothing beyond that — no mention of whether the rule applies immediately to live traffic, whether it persists across sessions, or how ttl expires it.

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?

Two tight sentences, the behavioral example first and the path-preservation nuance second. Nothing is padded.

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 destructive, open-world rule-creation tool with 5 parameters and no output schema, key facts are missing: what a `name` does, what `ttl` governs, and whether the mapping is active immediately. Adequate but with clear gaps.

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?

The trailing-* behavior on `to` is genuinely useful semantics not stated in the schema, and it disambiguates the two example forms. However `ttl` and `name` (undocumented at 60% coverage) get no explanation at all, so the description only partly compensates.

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?

States a concrete action — routing matching requests to another server — with a recognizable example (prod → staging). It never explicitly says it *creates* a mapping rule, and it does not name the sibling add_map_local, which is the main confusion risk.

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 prod→staging and local-dev examples give implied context for when this applies, but there is no explicit when-not guidance and no reference to add_map_local as the alternative for local-only mapping.

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

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

Annotations already declare destructive/readOnly/openWorld/idempotent status, and the description adds meaningful operation behavior: steps execute in order, compressed bodies are decoded first, and some step types are limited to request or response phases. It still does not explain rule persistence, TTL expiry, conflicts, or what existing rules are affected.

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 and dense: it states the core action first, then step ordering, then the supported step types. Every sentence carries operational detail without filler, though the type list is long.

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 destructive, no-output-schema mutation tool, the description explains the step language well enough to construct steps, but it omits rule lifecycle and several non-step parameters (ttl, name, methods, phase default). That leaves gaps an agent needs to call it safely and 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 only 33%, so the description must compensate. It thoroughly documents the central steps parameter by listing step types, field shapes, JSON-text semantics, and request/response constraints, but it leaves ttl, name, phase defaults, and methods undocumented.

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 ('Edit') and resource ('matching traffic in flight') and explains the ordered-step model, so the core purpose is clear. It does not mention sibling rule-management tools such as remove_rule or list_rules, so it lacks explicit sibling differentiation.

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?

There is no explicit when-to-use guidance or comparison with alternatives like set_breakpoint, add_map_local/add_map_remote, or remove_rule; the agent must infer usage from the purpose. The behavioral constraints (ordered steps, compressed-body decoding) are not usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds valuable scope information: it deletes every rule the agent created, implying cleanup rather than arbitrary deletion, which goes beyond the annotations.

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?

Two short sentences with the action front-loaded and the timing condition immediately following. No wasted words.

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 zero-parameter destructive cleanup tool, the description plus destructive annotations provide enough to invoke it correctly. It could mention whether deletion requires confirmation, but nothing critical for an agent is missing.

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?

The tool has zero parameters, so parameter semantics baseline is 4. There is no parameter ambiguity to resolve.

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?

Description states a specific verb and resource: 'Delete every rule you created.' The scope word 'every' and ownership phrase 'you created' help distinguish it from the singular remove_rule sibling, though no sibling is named explicitly.

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?

Explicitly says when to use it: 'Do this when you are done mocking or intercepting.' This gives clear lifecycle context but does not state when not to use it or name alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds meaningful scope beyond annotations by clarifying that ALL recorded traffic is deleted, including the user's own traffic.

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 short sentences, front-loads the action and scope, and adds only the necessary caution. Every sentence earns its place.

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 zero-parameter, destructive tool with rich annotations, the description is nearly complete: it states what is deleted and the required user intent. It could mention irreversibility more explicitly, but the destructive annotation already signals 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?

The tool has zero parameters, so the parameter semantics baseline is 4. There is no parameter information to compensate for or clarify.

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 and resource — "Delete all recorded traffic" — and adds useful scope with "(the user's too)." It does not explicitly distinguish this tool from siblings like clear_agent_rules or search_traffic, keeping it 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?

It gives a clear usage condition: "Only do this when the user asked for a clean slate." This is strong when-to-use guidance, but it does not name alternatives or explain what to use instead when the user wants partial cleanup.

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

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

The description presents a read-only comparison returning only differences with masked secrets, but the annotations declare destructiveHint=true. That directly contradicts the implied non-destructive behavior, and the description does not reconcile this discrepancy.

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 core operation and the list of compared fields, followed by concise usage guidance and return behavior. Every sentence contributes useful information without repetition.

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?

With no output schema, the description adequately explains what is returned: only differences across the listed request attributes, with secrets masked. It could specify the exact diff response structure or no-difference behavior, but it is largely complete for a two-parameter comparison 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 100%, and the schema already documents that a and b are request IDs with working/failing examples. The description reinforces that these are request endpoints but adds no syntax or format details beyond the schema.

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 states a specific operation—diffing two requests—and enumerates exactly what is compared: method, host, path, query parameters, headers, status, and bodies. This clearly distinguishes diff_flows from sibling tools like get_request or summarize_traffic.

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 gives explicit usage contexts: comparing a working request with a failing one, or comparing before and after an app change. It does not name alternatives or state when not to use it, so it falls short of a 5 but provides clear guidance.

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

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

Annotations cover the safety profile, so the description's job is to add context — and it does: bodies are "decoded," output is an excerpt rather than the full body, and headers are filtered by default. The one unexplained point is the destructiveHint=true on an obviously read-shaped tool, but the description does not contradict it.

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?

Two compact clauses; the payload summary is front-loaded and the second sentence is purely the paging hint. No filler or restated title.

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 6-parameter read tool with no output schema, key operational questions remain: how to obtain a valid id, how offset interacts with truncation when max_body_bytes is exceeded, and whether excerpts are mid-body continuations. The description is adequate but leaves an agent to discover these.

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 83%, so the schema already documents body, path, offset, all_headers and max_body_bytes thoroughly. The description only lightly reframes path/offset as a paging mechanism ("offset to read on"), adding marginal meaning over "for reading the rest" in the schema.

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?

"One request: timing, headers and a decoded body excerpt" names a specific verb+resource and enumerates exactly what is returned, which implicitly separates it from list_requests/search_traffic/summarize_traffic. It stops short of naming a sibling explicitly, so the contrast is inferred rather than stated.

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 never says when to reach for this tool versus list_requests or search_traffic, nor where the required id comes from. The only guidance is parameter-level ("Use path to pick part of a JSON body, offset to read on"), which is invocation help, not tool selection guidance.

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

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

Annotations already declare the read-only profile, so the lower bar applies; the description's contribution is enumerating the returned fields, which matters because there is no output schema. It does not state whether values are a point-in-time snapshot, whether the daemon must be running, or how current the counts are. The annotations themselves are internally odd (readOnlyHint=true alongside destructiveHint=true), but the description neither contradicts nor clarifies that.

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 fragment with zero filler, and the most important identifier (daemon state) leads. It is slightly under-specified rather than padded — it reads as a field list, not a complete sentence, which costs a point against the top mark.

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 zero-parameter, read-only status tool with no output schema, enumerating the returned fields is essentially the whole contract, and the description does that. Remaining gaps (snapshot semantics, daemon availability) are minor for this complexity level.

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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. It correctly spends no words on arguments.

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?

Names the resource precisely ('Daemon state') and enumerates the specific fields surfaced (proxy address, flow count, active rules, paused breakpoints, recording flag), so an agent knows exactly what this returns. It is a noun phrase rather than a verb+resource sentence, but the tool name supplies the verb and no sibling in the list is a status getter, so confusion risk is low.

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?

Provides no guidance on when to call this versus alternatives (e.g., list_rules for rule detail, list_requests for flow detail), no prerequisites, and no statement of freshness or cost. The agent must infer that a cheap read-only snapshot exists and when it is preferable to richer queries.

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

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

The description frames the tool as retrieving messages, but annotations declare destructiveHint=true (alongside readOnlyHint=true), so the safety profile is contradictory and not reconciled. With no warning about destructive or open-world behavior, an agent cannot infer the true risk.

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?

Three short sentences, front-loaded with scope and ordering. The pagination sentence is terse but every sentence carries needed information.

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?

Core call mechanics and ordering are covered, but with no output schema the description should say more about return shape or pagination response. It also leaves the contradictory destructive/open-world annotation issue unaddressed, so it is adequate but with clear gaps.

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 100%, so id/limit/max_text are already documented. The description adds pagination semantics for `after` and oldest-first ordering, but does not add meaning beyond the schema for the other parameters; baseline 3 applies.

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?

Identifies the resource precisely as messages of a WebSocket (status 101) request and states ordering. It distinguishes from generic request/traffic siblings by WebSocket scope, though it does not explicitly name an alternative or use a clear verb in the description itself.

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?

Explains pagination via `after` ('previous next'), which is actionable. It does not state when to choose this over get_request/list_requests/search_traffic or add any exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint and a contradictory-looking destructiveHint; the description adds only ordering ('newest first') and output shape ('one text line each'). It does not disclose truncation behavior, the default 20-row cap's consequences, or how the cursor interacts with filters, which is the kind of context annotations cannot carry.

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?

Short and front-loaded, but '(see format)' is a dangling reference to documentation the agent does not have, so a sentence that appears to earn its place actually adds no retrievable information. Two of the three clauses are informative; one is wasted.

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?

Ten parameters, no output schema, and the return value is described only as 'one text line each (see format)' plus an unexplained '×N' grouping that lives only in a parameter description. Without an output schema the description must explain the row format and next_cursor, and it explicitly defers both.

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 ten parameters are already documented in the schema (wildcards, '2xx', '10m' syntax, comma-separated methods). The description adds no parameter meaning beyond the filter-vs-paging hint, so the baseline 3 applies.

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?

States a resource ('requests') and ordering ('newest first'), and implies a list operation, but never uses a verb and never distinguishes it from siblings like search_traffic or get_request. 'Recent requests' leaves scope (recent within what session? what time bound?) undefined.

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?

'Filter rather than paging' is the only usage guidance and is implicit — it hints that parameters should be preferred over cursor iteration but never names an alternative tool or the conditions that would make one choose search_traffic or get_request instead.

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

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

Annotations already declare readOnlyHint, openWorldHint, destructiveHint, and idempotentHint, so the description's burden is lower. It adds that all rules are returned in evaluation order and references ownership constraints, but it does not explain the surprising destructiveHint=true for a list operation or describe return/pagination 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 only two short sentences and leads with the key scope and ordering information. However, the second sentence is about changing rules rather than listing them, so it does not fully earn its place for this tool.

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 zero-parameter, low-complexity list tool with no output schema, the description gives only a minimal scope and ordering statement. It is adequate for invocation, but it leaves return shape, filtering behavior, and pagination unstated.

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?

This tool has zero parameters, so the baseline is 4 and there are no parameter semantics requiring explanation in the description. The schema is empty and fully consistent with the absence of parameter guidance.

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 phrase "All rules in evaluation order" identifies the resource and ordering, but it does not use an explicit verb such as "list," so the agent must infer the operation from the tool name. The second sentence about changing rules is about mutation behavior rather than the listing purpose.

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 does not say when to use list_rules versus alternatives such as get_status or get_request, nor does it state any usage conditions or exclusions. The note about only changing rules you own is guidance for mutation tools, not for selecting this listing operation.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the description's only word, 'Delete', merely restates them. It adds nothing about permanence, whether a missing id errors, whether the deletion cascades, or whether re-running is safe — all relevant given idempotentHint=false.

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?

One short sentence with no filler, front-loaded and unambiguous in tone. The brevity is appropriate to its length, though it borders on under-specification rather than true conciseness.

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?

This is a destructive mutation with no output schema, an undocumented required id parameter, and no explanation of consequences or recovery. Given the complexity and risk profile, the definition leaves too much for the agent to guess.

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% for the single parameter 'id', yet the description does not explain what that id identifies, where to get it (presumably list_rules), or its format. With a low coverage schema, the description needed to compensate and does not.

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?

It has a specific verb (delete) and resource (rule), which is better than a tautology. But 'rules' is ambiguous in this toolset — siblings include list_rules, add_rewrite, clear_agent_rules, and add_map_local/remote — and the description does nothing to disambiguate which kind of rule this removes. No sibling is named.

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 never says when to use this versus list_rules (to obtain an id) or clear_agent_rules (bulk removal), and gives no prerequisites or confirmation guidance. The agent must infer all routing on its own.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: edits are merged into the replay, matching rules fire unless bypassed, and the response carries new ids with status and time. It doesn't state how a replacement body interacts with rules or what happens on partial failures.

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 front-loads the action, then packs the edit capability, the rules caveat and the return shape with zero filler.

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 10-parameter open-world mutation with no output schema, the description covers the payoff (new ids, status, time) and the rules interaction. Missing pieces are the multi-send semantics of count/concurrency and whether edits affect the stored flow, but nothing essential to a correct call is absent.

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 60%, leaving url, method, remove_headers and bypass_rules without descriptions or enums. The description meaningfully explains bypass_rules ('rules apply unless') and implies the edit-to-field mapping, but leaves the remaining undocumented parameters 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?

States a specific verb and resource ('Send a recorded request again') plus the key qualifier 'optionally edited', which distinguishes it from read-only siblings like get_request and list_requests. No sibling is named explicitly, so it falls short of 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?

The clause 'rules apply unless bypass_rules' implies the replay/re-issue use case and a toggle for escaping rule processing, but it never says when to choose this over alternatives such as get_request or diff_flows, nor any prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is covered. The description adds the useful scoping fact that edits apply to the paused phase, but says nothing about consequences of abort (whether the flow is dropped or errored) or whether the call blocks until the flow resumes.

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?

Two short sentences, zero filler, with the action set front-loaded and the phase constraint immediately after. Nothing is padded.

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 destructive-only, 8-parameter mutation with a nested object and no output schema, the description is thin. The biggest ambiguity is interaction between action and edit fields: must action=modify be set for url/body to apply, or are edits honored with action=continue? That is not resolved anywhere.

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?

With 75% schema coverage the baseline is near 3, and the description genuinely adds meaning: 'edits apply to the paused phase (request or response)' explains why url/method are request-phase only and status is response-phase only. It still doesn't state what happens if phase-inappropriate fields are supplied.

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?

States a clear verb set (continue, edit/modify, abort) against a specific resource (a flow paused by your breakpoint), so the agent knows exactly what the tool acts on. It signals the breakpoint workflow implicitly but never names sibling tools like set_breakpoint or wait_for_breakpoint to differentiate itself.

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 three action values are described in prose, and the note that edits apply to the paused phase gives some usage context. However, it never says when to use this versus wait_for_breakpoint, or what preconditions exist (e.g., a breakpoint must be currently paused), leaving the selection logic implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description usefully scopes the search to URL, headers and body. However, it discloses nothing about matching semantics (case sensitivity, regex, substring rules), result ordering, or the default/limit behavior, and it says nothing about the odd destructiveHint=true annotation, which an agent reading 'Find requests' would not expect.

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 front-loaded sentence with the verb and searchable scope stated first and no wasted words. Nothing could be trimmed without losing the field-scope information.

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?

Placeholder.

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 67% and the schema already documents 'query' and the 'in' enum; the description merely restates those same fields (URL/headers/body, 'some text'). The 'limit' parameter has a default but no description anywhere, and the description does not compensate for that gap.

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?

States a specific verb ('Find') and resource ('requests') plus the searchable fields, so the agent knows exactly what the tool searches. It does not differentiate from siblings like list_requests or summarize_traffic, so an agent must infer when this beats a plain listing.

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 phrase 'contain some text' implies a substring-search use case, but there is no explicit when-to-use, no mention of alternatives (list_requests, get_request, summarize_traffic), and no note on when this tool is inappropriate. Usage is left entirely to inference.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety profile is covered. The description adds genuinely new behavior beyond them: the request-vs-response interception point and, critically, that unanswered flows continue after timeout, which prevents an agent from fearing a permanent hang.

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?

Two sentences, zero filler, and the action plus the required follow-up sequence are front-loaded. No sentence could be removed without losing load-bearing information.

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 7-parameter, no-output-schema, destructive-intercept tool the description covers the invocation workflow but leaves lifecycle gaps: it never says how to undo or clear a breakpoint, that breakpoints persist for the ttl window (default 1h), or how concurrent breakpoints are keyed by name/url. Adequate to start, insufficient for confident full use.

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 only 43%, so the description needs to compensate and largely does not: url, methods, name, ttl and timeout get no explanation beyond what the sparse schema gives. The only added meaning is implicit — "before the server" vs "before the app" hints at the request/response values of the undocumented phase enum.

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?

States a specific verb and effect — pause matching requests before the server or responses before the app — which is more precise than the name alone and pins down where in the pipeline the pause occurs. It also names the two follow-up siblings (wait_for_breakpoint, resume_breakpoint), so an agent can distinguish this from the waiting/resuming tools without opening any 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?

The description establishes a clear workflow context: set the breakpoint, then call wait_for_breakpoint and resume_breakpoint, which is exactly the sequencing an agent needs. It stops short of exclusions — nothing is said about when to prefer set_throttle, wait_for_request, or remove_rule instead.

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

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

The annotations only flag destructiveHint=true and openWorldHint=true generically; the description adds the crucial blast radius ('Affects everyone using the proxy') and the reversal step (set enabled=false when done), which an agent could not infer from the schema. It stops short of saying whether in-flight or already-open connections are affected or how the change propagates.

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?

Two sentences, front-loaded with the purpose, zero filler. The global-impact warning and cleanup instruction both earn their place.

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 6-parameter mutation tool with strong annotation coverage, no output schema and no nested objects, the description covers what it does, who it affects, and how to undo it. Gaps are minor: it does not say whether the throttle applies immediately to in-flight requests or how connections are released on disable.

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 83%, so parameters are already largely self-documenting, including the profile enum and the custom option fields. The description only implicitly touches parameters via 'latency, then limited bandwidth' and does not explain preset behavior or how profile interacts with the custom fields, so it adds little beyond the schema.

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?

States a specific verb and mechanism ('Simulate a slow network (latency, then limited bandwidth)') plus the goal (reproduce timeouts and slow-loading bugs). It is clearly distinct from siblings such as set_breakpoint or add_rewrite, which have different intents.

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?

Gears usage to a concrete scenario (reproducing timeouts and slow loads) and gives an explicit lifecycle instruction: set enabled=false when done. That is a clear when and when-to-stop; it lacks only an explicit comparison to alternative approaches, of which there are none obvious among the siblings.

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

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

The description presents a read-only summarization operation, but the annotations declare destructiveHint=true, creating a serious contradiction about whether calling the tool can alter data. Although readOnlyHint=true aligns with the description, the contradictory destructive flag is unresolved and leaves the tool's behavior ambiguous.

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 short sentences with the most important guidance ('Start here') front-loaded. The remaining sentence compactly lists the return contents without boilerplate or repetition.

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?

With no output schema, the description does need to explain what comes back, and it names the key result categories including the useful last-flow-id detail for failing endpoints. It does not clarify limits, truncation, or behavior on very large windows, and it leaves the destructive-annotation conflict unaddressed.

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?

There is only one optional parameter, and the schema fully documents it with a default and examples like '5m', '1h', and 'all'. The description's phrase 'for a time window' reinforces its purpose but adds no syntax or meaning beyond what the schema already provides.

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 states a specific aggregate operation and enumerates exactly what is summarized: totals, status groups, grouped failing endpoints with their last flow ids, and the slowest request. This clearly distinguishes it from sibling list/search tools such as list_requests and search_traffic.

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?

'Start here' gives a clear indication that this is the initial overview tool, and 'for a time window' defines the scope of use. However, it does not explicitly name alternatives like search_traffic or list_requests, so the agent must infer when to switch tools.

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

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

The description's real contribution is disclosing that this call blocks, which annotations cannot convey, plus the fact that a matched flow is handed back. However it says nothing about what happens when the required timeout_seconds expires, whether that is an error or an empty return, or whether consumption of the paused flow mutates state (annotations claim both readOnlyHint and destructiveHint true).

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, front-loaded with the blocking behavior and ending with the routing hint. No filler, no restatement of the name.

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?

With no output schema, the description has to carry the return-value burden and only gestures at it ('return it for resume_breakpoint') without saying what identifying handle comes back. Combined with the unaddressed timeout outcome and the undescribed phase/url filters, a blocking, side-effect-flagged tool needs more.

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 only 67% and phase has an enum with no description at all, so the description needed to compensate and does not. It mentions no parameters: not the url pattern matching semantics, not the phase filter, and critically not what timeout_seconds expiring means for the caller.

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?

Names a specific verb and resource ('Block until one of your breakpoints pauses a flow') and immediately distinguishes itself from the related blocking sibling by naming the follow-up tool resume_breakpoint. An agent can tell it apart from wait_for_request and set_breakpoint without opening any 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?

The implied workflow (set a breakpoint, then block here, then call resume_breakpoint) is clear from the wording, and it explicitly names resume_breakpoint as the next step. But it never states prerequisites (do breakpoints need to exist first?), or how this differs from wait_for_request, which is the obvious alternative an agent would weigh.

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

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

The description adds useful behavioral context beyond the annotations by explaining that the call blocks and should be started before triggering the app action. However, it does not explain what happens on timeout, whether the request is consumed, or why the annotations include destructiveHint=true and openWorldHint=true.

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?

Two short sentences with no wasted text. The blocking behavior and operational sequencing are front-loaded and immediately useful.

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 core behavior and workflow are covered, but for a blocking tool with a required timeout and no output schema, the description omits important context such as timeout failure behavior and the shape of the returned request.

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 already 80%, so the schema carries most parameter meaning. The description only says the URL matches, without adding detail about method, status, since_seconds, or timeout_seconds behavior beyond what the schema provides.

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 states a specific verb and resource: it blocks until a matching request completes and returns that request. This is clear and distinct from immediate retrieval tools like get_request, but it does not explicitly differentiate itself from the similarly named sibling wait_for_breakpoint.

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 gives a clear usage pattern: start this tool, then trigger the action in the app. That tells the agent when this tool is appropriate, though it does not name alternatives or explain when not to use it.

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