find_requests

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

With no annotations, the description carries the full burden and does well: it discloses the limit cap (max 500), that the total match count is always reported even when results are truncated, and that URLs are masked unless include_secrets=true — a security-relevant default an agent would otherwise miss. It never states read-only/non-destructive behavior or whether the HAR file is modified.

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?

Front-loads the purpose and output contract, then packs filter semantics into tight clauses with zero filler. Every sentence conveys a distinct, actionable constraint.

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 detail is unnecessary and correctly absent; the description still adds the truncation/count behavior. For an 11-parameter tool it is nearly complete, missing only the meaning of the required `path` input and the `method` filter.

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% across 11 params, so the description must compensate, and it largely does: it explains url_contains/url_regex matching mode, status value formats, mime/domain substring semantics, the start_ms/end_ms reference origin, the limit ceiling, and include_secrets. The required `path` parameter and `method` are never explained anywhere, which is the main remaining 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+resource ("Find requests") and pairs it with the concrete output contract ("get their #index numbers"), plus names the downstream tool request_detail. It does not explicitly separate itself from slowest_requests or failed_requests, which overlap with the status filter it documents.

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?

Gives real usage rules: all filters are ANDed, url_contains/url_regex are case-insensitive, status accepts 404/4xx/200-299/0/comma lists, mime and domain are substring matches, and start_ms/end_ms select on request start time in ms from the first request. No explicit when-not or sibling routing guidance (e.g., "prefer failed_requests for 4xx/5xx overview").

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