charles-mcp

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

With no annotations, the description bears the full disclosure burden, and it does add real value: headers and body are redacted, the body is bounded and only returned on request, and bodies must be enabled server-side. It does not state that this is a read-only operation or what happens when bodies are disabled.

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 compact clause with no filler and the optional-body caveat placed at the end where it reads naturally. It is efficient, though the missing subject makes it read as a fragment rather than a purposeful 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?

An output schema exists, so return-value explanation is not required, and the redaction/bounding notes cover the riskiest behavior. What remains missing is routing versus get_response and how to obtain the required transaction_id, which matters for a 3-parameter lookup tool in a crowded sibling set.

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 description reinforces the include_body/max_body_bytes semantics (optional, bounded, redacted), though most of that detail is already in the schema. The required transaction_id is not mentioned in the description at all, so it adds little beyond the structured fields.

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 is a noun-phrase inventory of what comes back (request line, redacted headers, timing, sizes, optional body) rather than a verb+resource statement. It hints strongly that this retrieves the HTTP request for a transaction, but it never says so outright and does not distinguish itself from the sibling get_response.

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 when-to-use guidance, no mention of the sibling alternatives (get_response, list_requests, search_traffic), and no note that transaction_id should be sourced from list_requests — that hint lives only in the schema. Usage must be inferred entirely from the name.

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?

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: headers are redacted, the body is bounded and redacted, and body retrieval is optional and gated behind a 'bodies enabled' switch. It does not cover failure modes (e.g., missing/expired transaction, body unavailable) or permission requirements, leaving notable gaps for a read 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?

A single compact sentence with no filler, and the most important information (status, headers) is front-loaded. The parenthetical redaction qualifiers are efficient and 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?

The output schema exists, so the field inventory is somewhat redundant, yet the description omits practical context such as where transaction_id comes from (only in the schema) and when to prefer this over get_request. For a 3-parameter read tool it is adequate but leaves routing decisions to inference.

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 itself documents include_body ('needs bodies enabled') and gives a transaction_id example. The description only echoes the optional/redacted nature of include_body and adds no semantics for max_body_bytes, so it is roughly at the baseline rather than compensating for the 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?

The description is a noun-phrase inventory of return fields ('Status, headers, timing, TLS/connection info... response body') rather than a verb+resource statement, so the action ('retrieve the response for a transaction') is only implied. It never distinguishes itself from siblings like get_request or get_status, which an agent must infer from the field list alone.

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 call this versus get_request, get_status, or get_session_summary. The 'optionally... (needs bodies enabled)' phrase hints at a prerequisite but frames no usage conditions 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?

With no annotations provided, the description carries the full behavioral burden. It discloses output content categories but does not state that the operation is read-only, whether it has side effects, permission requirements, pagination/limits, or what 'indexed traffic' excludes.

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?

It is a single compact sentence with no filler, and the summary content is front-loaded. It is slightly fragmentary but still appropriately sized for the 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?

An output schema exists, so return values need not be fully described, and the description identifies the main aggregate categories. However, with no annotations and an undocumented top parameter, it is only minimally 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 only 50%: session_id is documented in the schema, but the top parameter has only a default and min/max constraints. The description does not explain what top controls or how session_id scopes the summary.

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 that the tool produces aggregate counts by host/method/status, recent errors, and total sizes for indexed traffic. That distinguishes it from request-level siblings like list_requests and get_request, though it does not name alternatives 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?

It implies the tool is for summarized/indexed traffic rather than individual request retrieval, but gives no explicit when-to-use guidance, prerequisites, or comparison to sibling tools such as search_traffic or list_requests.

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?

With no annotations, the description carries the burden, and it does convey that this is a state-reporting read exposing counters and safety settings. It omits whether the call is side-effect free, whether it is cached/cheap, or any auth/latency context an agent would want before polling 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?

A single compact clause with zero padding, front-loading the most important item (bridge connectivity). It is a noun phrase rather than a sentence, so it reads as a return-value stub rather than a self-contained definition.

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 output schema already documents return values, so the description's field enumeration largely duplicates structured data instead of adding the guidance an agent needs (when to poll, how it relates to session/traffic tools). For a zero-param diagnostic getter the bar is low, but the description still stops short of full context.

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 and the schema is empty, so there is no parameter semantics to explain; baseline 4 applies. The field list in the description maps to returned data rather than inputs, and adds no confusion.

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 enumerates exactly what the tool reports (bridge connectivity, Charles version, recording state, counters, safety settings), so the resource is unmistakable even though there's no explicit verb. It does not differentiate from siblings such as get_session_summary, which could plausibly overlap in reporting state.

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 statement of when to call this versus get_session_summary or watch_requests, and no exclusions or prerequisites. The agent must infer that this is a health/diagnostic snapshot call.

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?

With no annotations, the description carries the full burden, and it does disclose two meaningful traits: results are compact summaries with redacted URLs, and pagination is cursor-based. It does not state defaults, ordering semantics beyond what the schema says, safety/read-only nature explicitly, or rate limits. Useful but incomplete for a 12-param tool with zero annotation coverage.

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 compact sentence with the resource and the two most important behavioral facts front-loaded. Efficient, though the terseness leaves the 12-parameter surface under-explained.

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 shape need not be spelled out, and the description does hint at redaction and compactness. But for a tool with 12 optional filter parameters, no annotations, and a non-obvious cursor-vs-time-filter relationship, the description is thinner than the complexity warrants.

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 only 50%; limit, state, method, status, status_class, and url_contains have no descriptions in the schema. The description says only 'with filters,' adding no meaning about what can be filtered, no note on how the filters combine, and no clarification of the since_ms/until_ms vs cursor 'after' relationship — the single most confusing interaction in this 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 (List) and resource (captured requests), and adds useful scope detail — compact summaries, redacted URLs, cursor pagination — that clarifies what kind of listing this is. It does not explicitly differentiate itself from search_traffic or watch_requests, which is the only thing keeping it from 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 mention of filters and cursor pagination implies the browse/paginate use case, but there is no explicit when-to-use guidance and no reference to alternatives like search_traffic (broader search) or watch_requests (live streaming). The agent must infer the routing decision from sibling names alone.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the search is bounded, over recent traffic, and uses redacted URLs/headers while bodies are only searched if enabled, but it does not explicitly state read-only behavior, permissions, performance limits, or what 'bounded' means operationally.

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 compact sentence with no wasted words. The scope ('bounded'), target ('recent traffic'), and field-level caveat ('if enabled') are front-loaded efficiently.

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 5-parameter search tool with no annotations and only 40% schema coverage, the description is too sparse. The output schema reduces the need to explain return values, but missing guidance on parameter roles, alternatives, and bounded-scan behavior leaves the definition incomplete.

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 description maps 'URLs, headers and (if enabled) bodies' to the fields parameter and adds the important redaction qualifier. It does not mention host, limit, max_scan, or the query parameter's semantics, leaving notable gaps given only 40% schema description 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 uses a specific verb and scope ('Bounded search over ... recent traffic') and names the searchable surfaces (URLs, headers, bodies). It is clear this is a search operation rather than a list or fetch, though it does not explicitly contrast itself with siblings like list_requests or get_request.

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?

Usage is implied by 'search over ... recent traffic', which suggests a scoped lookup use case. However, there is no explicit guidance about when to choose this over list_requests, get_request, or watch_requests, nor are exclusions or prerequisites stated.

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?

With no annotations, the description carries the full burden, and it does disclose the most important trait: this is a non-streaming pull loop, not a subscription. It omits retention/expiry behavior for old cursors, ordering guarantees, and any rate-limit or cost note, which matter for a repeated-poll 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 short sentences, payload first, calling mechanics second — well front-loaded with almost no waste. The only inefficiency is the ambiguous 'next_after' reference, which costs a moment of interpretation rather than adding clarity.

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 tool is simple and an output schema exists, so return values need not be explained. Still, for a cursor-based poller the description should resolve what the next cursor is and what happens when 'after' is stale or past retention, and it leaves that gap plus the next_after/after ambiguity unresolved.

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 50%: 'after' is documented in the schema while 'limit' is not. The description adds cursor-advance semantics but refers to 'next_after', a name that does not exist in the input schema, leaving the agent to guess whether that is a response field or the same thing as 'after'.

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 concrete payload: raw lifecycle events (request_created through response_complete/failed) retrieved since a cursor. That is specific enough to separate it from list_requests or get_status, though it never names a sibling or explicitly contrasts 'raw events' with the summarized views the other tools return.

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 explains the calling pattern well — this is a pull, re-invoke to get newer events, it does not stream — which is genuine usage guidance for polling. However it gives no selection criteria against siblings (list_requests, search_traffic, get_session_summary), so an agent knows how to call it but not when to prefer it.

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