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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes further by disclosing temporal edge behavior: unfinished periods return only completed hours (pendingBuckets > 0) and today has no data until it ends. It also scopes the call to production and the default service. It does not discuss rate limits, auth, or cost of 'full' detail beyond the schema note.

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-loaded with the payload contents, then routing, then edge cases — a sensible order with no filler sentences. The final sentence is long and packs two distinct escape hatches together, which slightly hurts scanability but every clause carries 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. What remains — when the data is incomplete, what scope is covered, and where to go otherwise — is all present, making the definition 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?

With 75% schema coverage, the baseline is 3, and the description adds beyond it: 'Daily, weekly or monthly' implicitly documents the undescribed granularity enum, and it explains the comparison semantics of date ranges. The detail parameter is left to the schema, so it is not fully compensated but the gap is minor.

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 ('performance report for a past date') and enumerates the payload (total requests, error rate, p95, top 20 transactions by impact, timeline). It explicitly distinguishes itself from tideways_get_performance_summary and tideways_get_performance, so an agent can route without opening schemas.

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 the positive case ('Use to compare days or weeks') and names concrete alternatives for the cases it does not serve: tideways_get_performance_summary for unfinished periods and tideways_get_performance with end + minutes=1440 for other environments/services. Exclusions and routing are both explicit.

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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real behavioral detail beyond that: the stack trace is capped at the first 15 frames, the latest occurrence carries request context (URL, method, status, host, service), and occurrences are bucketed over the retention period. It does not mention latency, payload size, or rate limits, so not a 5.

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 sentences, front-loaded with the identity of the resource before the enumerated payload. The middle sentence is dense but each clause maps to a distinct output component. Slight redundancy between the second and third sentences (both reference how the issue was listed) keeps it from a 5.

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 explanation is optional, yet the description still names the main result components, and annotations carry the safety profile. The dependency on tideways_list_issues for a valid id/type is made explicit. Missing only edge-case guidance such as behavior for an invalid id or type mismatch.

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 every parameter (including the detail and project enums) is already documented in the schema. The description's "Pass the id and the type the issue was listed under" largely restates the schema text for issueId and type, adding workflow framing but little new syntax or constraint detail. 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 specific verb and resource ("Get one issue") and explicitly scopes it against the sibling it comes from ("from tideways_list_issues"), then enumerates the depth of data returned. An agent can distinguish this from tideways_list_issues and tideways_get_transaction without opening a 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?

"Use to point at the failing code, rank the affected endpoints, and say when the issue started, peaked or stopped" gives concrete use cases, and the workflow dependency on tideways_list_issues is stated twice. No when-not guidance or alternatives (e.g. get_transaction) are named, so it stops short of a 5.

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?

Goes beyond the read-only/idempotent annotations by disclosing real limitations: findings do not name affected requests and the API cannot filter traces by bottleneck. It also prescribes the workaround (give the user the link, whose UI page lists recent affected traces). This is exactly the kind of operational caveat annotations cannot convey.

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 what the tool returns, then usage context, then caveats — a sensible information hierarchy. It is dense but every sentence carries information; the density is justified for a tool whose limitations matter.

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 needn't be explained, and the description still covers the tool's behavioral limits and the recommended follow-up action. Complete enough to call correctly, with only the sibling-routing gap keeping it below 5.

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 project/service/environment semantics (defaults, error-on-unknown, cross-references to tideways_list_projects/services) are already fully documented in the schema. The description adds nothing about parameter behavior, 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 specific verb and resource: automatic findings (PHP config problems and code bottlenecks) that Tideways produced for a project. The concrete examples (OPcache buffers, timeouts, N+1 queries, sleeps, waits) make the output identifiable and separate it from performance/metric siblings such as tideways_get_performance.

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 frames the use case ("quick health check or optimization ideas") and warns against misuse ("Do not infer N+1 queries from slow-SQL issues"). It does not, however, name a sibling alternative (e.g. tideways_list_issues or tideways_search_traces) to route the agent when this tool is the wrong choice.

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/idempotent/non-destructive safety profile, but the description adds real behavioral context beyond them: zero-filled results for windows older than ~30 days, downsampled timelines above 60 minutes, and a warning that detail=full 'can be very large'. It omits any note on permissions or response size limits, but the data-behavior disclosures are substantive.

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 sentences with no filler, and the window definition plus payload contents lead the description. The first sentence is long and clause-heavy, but each clause carries routing or content information rather than padding.

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 spelled out, yet the description still summarizes the shape (totals, top transactions, timeline). Combined with the sibling routing and data-horizon caveats, nothing an agent needs to call this 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 both the schema and the description document every parameter; the description largely restates the minute range and default end time. It adds the ~30-day data horizon, which the schema lacks, but otherwise defers to the schema. Baseline 3 applies when the schema does the heavy lifting.

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 verb+resource (performance metrics for a window) and enumerates the exact payload: totals, top 20 transactions by impact, and a timeline. It explicitly differentiates itself from siblings tideways_get_history and tideways_get_performance_summary.

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 states when results degrade ('Older windows return zeros') and routes to the correct alternative ('use tideways_get_history for them'), plus a second routing rule for 15-minute trends ('use tideways_get_performance_summary'). Both when-to-use and when-to-use-something-else are explicit.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond that: the aggregation granularity (15-minute buckets), the retention window (~30 days), and that totals are included. It stops short of disclosing latency, rate limits or auth requirements, so it edges above baseline without being exhaustive.

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 sentences, zero waste, and front-loaded with the return shape before the routing advice. Each 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?

With an output schema handling return values, full parameter documentation, and annotations covering the safety profile, the description only needs to add granularity and routing – both of which it does. An agent has everything required to call 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?

Schema description coverage is 100%, so every parameter is already documented (hours limits, detail concise/full, project/service/environment resolution and fallbacks). The description only echoes the `hours` window, adding no syntax or format meaning beyond the schema, so the baseline of 3 is correct.

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 plus exactly what is returned: requests, errors and p95 response time in 15-minute buckets with totals. It explicitly names the sibling tool that handles a different granularity (tideways_get_performance), so the agent can tell the two apart without opening either 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?

"Use for trends, before/after comparisons and spotting incidents" gives concrete use cases, and "For per-minute detail and top transactions use tideways_get_performance" names the alternative and the condition that selects it. Nothing is left 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds valuable behavioral context beyond that: the window cap (1-1440 minutes), downsampling above 60 minutes into buckets, the default end=now, and the rich result shape (per-minute metrics plus a response-time histogram and totals).

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 sentences, front-loaded with what the timeline returns, then the diagnostic use case, then the ID source. The metric enumeration is dense but every clause carries information; no filler sentences.

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 an output schema present, the description needn't explain return values, yet it still sketches them usefully, and it covers windowing, defaults, and ID provenance. It omits any mention of the project/service/environment scoping parameters, but those are fully documented in the schema, so nothing essential is missing 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 every parameter including defaults and the downsampling rule; baseline is 3. The description's mention of the 1-1440 range and bucketing largely restates the schema rather than adding new syntax or format meaning, and project/service/environment scoping is left entirely to 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 concrete verb+resource ('Timeline of one transaction') and enumerates exactly what the timeline contains (requests, errors, p95/median/average, time per layer, histogram). It also names the sibling tool that supplies the ID, so an agent can distinguish it from tideways_get_performance and tideways_get_performance_summary.

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 an explicit usage condition ('Use it to see when a transaction got slow and in which layer') and tells the agent where to obtain transactionId (transactions[].id of tideways_get_performance), which is real routing guidance. It stops short of stating when not to use it versus get_performance_summary, so it is not a full when/when-not/alternatives treatment.

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: 10-per-page paging with a total count, newest-first ordering, one type and one status per call, no time filtering, and how service/environment defaults resolve. It omits return-shape and error/pagination-failure behavior, so not a 5.

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-loaded with purpose, sorting and page size before the scoping caveats; dense but nearly every clause carries information. Slightly sentence-heavy with several defaults packed into one paragraph.

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 no explanation, and the description covers scope, defaults and filtering adequately. The only gap is that it never points to tideways_get_issue for per-issue detail, which matters given nine siblings.

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 baseline is 3, but the description contributes beyond it: the single-type/single-status-per-call constraint and the default-resolution rules for service and environment. It largely parallels what the schema already documents for page, type, status, detail and transactionIds.

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 (list issues of a project) with scope details: the five issue types, sort order (newest occurrence first), page size (10) and total count. This is clearly distinguishable from the singular sibling tideways_get_issue.

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 to find what is failing or slow and how often" gives an explicit context, and the description routes the agent (tideways_list_projects for valid names, tideways_list_services for services) plus notes there is no time filter and to use lastOccurred for recency. It does not name tideways_get_issue as the alternative for drilling into one issue, so it stops short of full when/when-not coverage.

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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real context beyond that: results are limited to the caller's configured token scopes and include a rate-limit reading, which tells the agent why an empty or partial result may occur.

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 sentence for what it returns, one for when to call it, both front-loaded and free of filler. No sentence restates the name or annotations.

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 no elaboration. For a parameterless, read-only discovery tool the description covers purpose, invocation trigger, and the token-scoped nature of the result, leaving nothing material 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?

Zero parameters, so the schema carries no parameter semantics for the description to enrich. Baseline of 4 applies; nothing further is needed here.

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 (List) and resource (projects and scopes) scoped to the configured API token, plus a secondary payload (remaining hourly rate limit). This is clearly distinguishable from every sibling, which all operate on issues, services, traces, or performance 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?

Gives explicit triggering conditions: call first when the right project is unknown, or after a scope or unknown-project error. It establishes precedence over other tools but does not name a specific alternative or state when not to call it.

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?

Goes well beyond the annotations (which already mark it read-only/idempotent) by disclosing cost (4 requests plus 1 per service, capped at 30, reduced under rate limits) and a real scope limitation: only services named by the newest open/ignored issues are listed, unlike the UI selector which lists all. This is the kind of behavior an agent needs before calling.

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 core purpose is front-loaded in the first sentence, and the cost and scope sentences each carry weight. Some phrasing is dense and slightly awkward ('named by its issues', 'so the first ones serve it'), but there is no 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?

With a rich output schema already covering return values, the description completes the picture by covering when to use it, the search parameter's role, request cost, rate-limit behavior, and the listing-scope limitation. Nothing an agent needs to invoke it 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 coverage is 100%, so the schema already documents all three parameters in detail, including search semantics and environment defaults. The description reinforces the search flow ('one word of it' → sorted by matching traces) but adds little beyond what the schema descriptions state; baseline 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?

Specific verb+resource: it lists the services of a project, enumerating the kinds (web, APIs, workers, CLI) and noting the default service leads. It also distinguishes itself from siblings by contrasting with tideways_search_traces when the default service misses a transaction.

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?

Explicit trigger conditions are given: call it when the user names an app/API/worker that is not a project, or when tideways_search_traces fails to find a transaction in the default service. It names the alternative and the exact condition that selects this 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?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower; the description nevertheless adds real behavioral facts beyond them: default page size of 30 (max 100) and the default sort order (newest first unless sortBy is set). It does not repeat the schema's warning about detail="full" being very large, which is the one behavior worth surfacing at selection time.

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: the first front-loads result contents and default paging/ordering, the second front-loads the use case before the filter list. The dense parenthetical earns its space by answering 'how many, in what order' in one clause.

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 13 optional params, an output schema, and 85% schema coverage, the description supplies the missing selection-level context (defaults, ordering) and need not explain return values. It omits only the caveats about from/to being mutually required and the verbose detail="full" payload size, which are relevant before calling but are covered in the schema.

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 85%, so the schema already documents nearly every parameter in detail; the description mainly summarizes (limit, sortBy, transactionIds, text, time window, response time). It adds the ordering default only implicitly ('newest first unless sortBy is set'), which duplicates the sortBy schema text rather than extending it. Baseline 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?

States a specific verb and resource ("Find individual request traces") and immediately lists what each result carries: response time, memory, bottlenecks, slowest layers. That contrasts cleanly with siblings like tideways_get_transaction (single trace) and tideways_get_performance (aggregated data), so an agent can pick it without opening the 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?

Explicitly gives the use case ("investigate specific slow or failing requests") and names tideways_get_performance as the upstream source for transactionIds, which is a concrete routing rule. It stops short of saying when *not* to use it (e.g. versus tideways_get_transaction for a single known trace), so it is contextually clear but has no exclusions.

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