phpray

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

With no annotations, the description carries the behavioral burden. It discloses that the result is a snapshot of currently firing alerts, covers every accessible site, and is sorted with the worst overrun first. It does not describe side effects, but nothing in the description suggests mutation.

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 a single compact sentence that front-loads the key idea, then adds scope and ordering. Every word contributes information, with no filler 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?

For a zero-parameter read-style tool with no output schema, the description is complete: it says what is returned, the scope, and the ordering. An agent can correctly select and invoke this tool without further clarification.

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 and the input schema is empty, so schema coverage is effectively complete. There are no parameter semantics for the description to add; baseline 4 applies for a no-parameter tool.

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 identifies the resource ('alerts'), their state ('currently firing'), the scope ('across every site this token can see'), and the ordering ('worst overrun first'). This clearly separates it from sibling tools like phpray_errors or phpray_slow_queries, which cover different data.

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 contextual guidance: use this when you want currently firing alerts across all sites the token can see. It does not explicitly name when-not-to-use or alternatives, but its scope and resource are specific enough for a zero-parameter tool.

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. It does disclose a default behavior (if no range given, compares day before yesterday vs last 24h), which is useful. However, it does not mention whether the tool is read-only, what the output format is, or any constraints like authentication or rate limits.

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 concise at two sentences, with the purpose front-loaded and a clear usage example. Every sentence earns its place without redundancy.

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 has 5 parameters, 1 required, no output schema, and no annotations. The description explains the purpose and a default but does not describe what the tool returns (e.g., a table, metrics), nor does it differentiate from siblings like phpray_overview or phpray_traces. Given the complexity and lack of annotations, more context is needed.

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 the baseline is 3. The description adds minimal value beyond the schema—only clarifying that 'from_a' is the earlier start and giving a default. It doesn't explain the relationship between ranges A and B further or any parameter interactions.

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 compares two time ranges for one site side by side, and implies a comparison for evaluating changes. It's not a tautology and the purpose is understandable, but it doesn't specify what metrics are compared (e.g., performance, errors), which slightly limits clarity.

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 a specific use case: checking whether a deployment, plugin update, or configuration change improved or worsened things. This provides clear when-to-use guidance, though it doesn't mention alternatives or when not to use the tool, leaving some ambiguity.

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 burden of behavioral disclosure. It does add a genuine behavioral note — results are empty when function profiling is off — which is useful. However, it omits the return shape, aggregation behavior, and any ordering guarantees, so coverage is partial.

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 with no filler, front-loaded with the core purpose and the diagnostic question it answers. The behavioral caveat earns its place at the end. Efficient without being under-specified.

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 list-retrieval tool with a complete parameter schema and no output schema, the description covers the core semantics and adds a valuable caveat about profiling being off. It could mention return format but is otherwise sufficient 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 100%, so the schema already documents all three parameters (site_id, limit, window_minutes). The description adds no parameter-level meaning beyond the schema, matching the baseline for fully-documented schemas.

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 resource (component time attribution) with a concrete verb and answers a direct diagnostic question ('which plugin is slowing the site down'). Clearly distinct from siblings like phpray_slow_pages and phpray_slow_queries, which target pages and queries respectively rather than plugin/theme/vendor attribution.

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 choose this tool over its siblings. The description mentions a condition ('Empty when function profiling is off') but never names alternatives or exclusion criteria, leaving the agent to infer selection logic from context.

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?

No annotations are present, so the description carries the full burden. It clearly discloses what the tool returns (PHP errors with file/line, 5xx without PHP errors) and hints at the output containing ids via the phpray_trace reference. It doesn't mention ordering or pagination, but these are minor for a list 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 with no fluff. The primary purpose is front-loaded, and the second sentence adds a valuable cross-reference to phpray_trace. Every word 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 list tool with no output schema, the description provides sufficient context: what it returns, the nature of failures, and how to drill down. It doesn't detail the exact response structure, but that is likely inferred from the context and is not critical for calling the tool 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 100%, so the baseline is 3. The description adds no additional meaning about limit, site_id, or window_minutes beyond the schema, but it doesn't need to since the schema already documents them.

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: lists failed requests on a site, distinguishing PHP errors/warnings (with file/line) from 5xx responses without PHP errors. This clearly separates it from siblings like phpray_slow_pages (performance) or phpray_traces (all requests).

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 explicitly routes the user to phpray_trace for deeper investigation of an individual error, providing a clear alternative. It implies this tool is for the list-level view, though it doesn't explicitly exclude other siblings like phpray_alerts or phpray_compare.

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 of explaining behavior, and it does enumerate the metrics returned. However, it does not state whether this is strictly read-only, what the response shape looks like, or any limitations such as window boundaries or missing data behavior. It is not misleading, but it leaves the output format to inference.

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 no filler. The metric list is front-loaded and the usage guidance is a separate, actionable sentence that 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 low-complexity tool with two parameters and a clear metric list, the description is mostly complete. The main gap is the lack of any return structure detail, which would be more important given there is no output schema, but the tool is simple enough that an agent can call it correctly from this description.

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%, with both site_id and window_minutes already described clearly. The tool description adds no additional meaning about these parameters, so the baseline score of 3 is appropriate.

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 identifies the resource (one site, over a time window) and the specific content (requests, errors, latency percentiles, database share, N+1 count), so an agent knows exactly what this tool returns. It lacks an explicit verb like 'retrieves' and does not name a sibling to distinguish from, though 'before digging into anything else' positions it as the entry-point overview.

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?

'Use this before digging into anything else' is explicit guidance on when to invoke this tool: it is the first step before deeper investigation. It does not name specific alternatives or give when-not-to-use conditions, but the placement guidance is clear given the sibling tool set.

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 behavioral disclosure burden. It reveals token-scoped visibility ('this token can see') and the type of data returned. As a zero-parameter listing operation, the behavior is mostly self-evident, though it does not describe output formatting.

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, no filler. The tool's purpose is stated first, and the critical usage instruction is front-loaded in the second sentence. Every word 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 simple, zero-parameter list tool, the description is complete: it explains what the tool returns, the token scoping, and how the output feeds into the rest of the system. No output schema or additional nuance is needed for an agent to use 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?

There are zero parameters, so the baseline is 4. The description adds relevant context about what the returned site list is for, which is more than enough given the empty input 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 uses a specific verb and resource: 'List the PHP sites this token can see' and names the response contents (requests, p95 latency, error rate). It clearly identifies the tool's scope, though it doesn't explicitly contrast itself with any sibling tool, which prevents 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 description gives direct usage guidance: 'Start here: every other tool needs a site_id from this list.' This explicitly tells the agent when to use this tool and why it is the prerequisite for the rest of the workflow.

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 that this is a read-oriented listing, the data source (request timeseries), and the response contents (URLs, request counts, p95). This is sufficient for a simple read-only tool, though it does not specify ordering details beyond the word 'slowest'.

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 no filler. The primary result is front-loaded, and the second sentence sharpens the intended use case without redundancy.

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 low-complexity read-only tool, the description plus fully documented schema cover what an agent needs: inputs, output content, and purpose. There is no output schema, but the mentioned fields are concrete enough to interpret results. It could add an explicit note about ordering, but this is not a significant gap.

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 three parameters are already documented in the input schema. The description adds no new parameter-level meaning, which matches the baseline of 3.

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 names a specific resource ('slowest URLs on a site') and the exact metrics returned (request counts and p95). It also frames the intended question ('which page is slow'), which distinguishes it from sibling tools like phpray_slow_queries that target database queries.

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 identifies the use case: investigating slow pages from request timeseries data. It stops short of explicitly contrasting with alternatives such as phpray_slow_queries or stating when not to use it, so it misses the top score by only a small margin.

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 of behavioral disclosure. It usefully states that literals are already masked and that the result is ordered by time spent, which adds real context. However, it does not explicitly state whether this is read-only, whether any filtering is applied, or what the caller field contains when unknown.

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 with no filler. The product definition, ordering, included fields, masking behavior, and intended question are all 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 simple listing tool with three plain parameters and no output schema, the description explains the key result contents: fingerprints, time ordering, call counts, caller, and masking. It could be slightly richer about the exact return shape, but nothing critical needed to call the tool correctly 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?

Schema description coverage is 100%, so the schema already documents limit, site_id, and window_minutes. The description adds no additional parameter-level meaning beyond implying that the result focuses on slow queries, so the baseline score of 3 is appropriate.

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 names a specific resource (SQL fingerprints), a clear ordering principle (by time spent), and includes what is returned (call counts, caller when known). The quoted question "which query is slow" makes the tool's intent unmistakable and distinguishes it from siblings like phpray_slow_pages.

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 "Answers 'which query is slow'" gives a clear context for when to use this tool. It does not explicitly name alternatives or say when not to use it, but the SQL-specific scope provides enough direction relative to the sibling 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?

With no annotations, the description carries the burden of disclosing behavior. It lists return contents but does not mention whether the operation is read-only, what happens if the trace_id is invalid, or any limitations (e.g., 'when the request was profiled' suggests profiling must be enabled). It provides some context but is not fully transparent.

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 a single efficient sentence that front-loads the core purpose and enumerates the included components. It is slightly dense but contains no wasted words. A more structured list could improve scannability, but it is concise and informative.

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 tool with no output schema and a single parameter, the description lists the main expected content (queries, external calls, errors, breakdown) and notes a caveat ('when the request was profiled'). However, it does not specify the exact format, nesting, or error behavior, leaving some ambiguity for a potentially complex response.

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 parameter description 'Trace id from phpray_traces' provides a useful source reference. However, the tool description adds no additional semantics beyond the schema, and the schema description is minimal, so it meets the baseline without exceeding it.

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 specifies the tool's purpose: it returns full details of a single request including wall time split, queries, external calls, errors, and component breakdown. This distinguishes it from siblings like phpray_traces (which likely lists trace IDs) and phpray_components (which focuses on breakdown).

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 the phrase 'One request in full' and the parameter description 'Trace id from phpray_traces,' suggesting you first obtain a trace ID from the sibling tool. However, there is no explicit guidance on when to choose this over alternatives or when not to use it, so it relies on 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it returns recent requests and can be filtered. It does not mention whether it is read-only, the output format, pagination, or any error conditions. For a tool with no output schema, this is a significant gap.

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 fluff, with the core purpose front-loaded and a natural workflow transition. Every word 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?

Despite the concise nature, the description omits critical operational details. There is no output schema, so an agent does not know what fields are returned (beyond an id for phpray_trace), whether results are paginated, or what happens when filters yield nothing. For a 5-parameter tool, this is insufficient for confident 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 coverage is 100%, so the baseline is 3. The description adds semantic weight by suggesting min_ms and status are used to 'find the bad ones,' which hints at slowness and error filtering beyond the schema's dry descriptions. This is a meaningful addition.

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 'Recent requests for a site' – a specific resource and action. It also mentions filtering by min_ms and status, and points to phpray_trace for a detail view, effectively differentiating itself from that sibling. The purpose is unmistakable.

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 provides a concrete use case: 'Filter with min_ms and status to find the bad ones' and a workflow pointer: 'then pass an id to phpray_trace.' This tells an agent when to use this tool (to list/filter requests) and that phpray_trace is for individual traces. It lacks explicit exclusions for other siblings like phpray_errors, but the guidance is adequate.

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