Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Tideways MCP Server why was checkout slow yesterday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A read-only Model Context Protocol server for Tideways. It lets an AI assistant answer questions such as "why was checkout slow yesterday?" from your performance data, issues and traces. It only calls GET endpoints of the Tideways REST API.
You need a Tideways API token with the scopes metrics, traces and errors (Organization settings → API Access), and Node.js 22+ or Docker. Coming from 1.x? See UPGRADING.md.
claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-serverAdd -s user to use it in every project.
Open the .mcpb bundle from the latest release. It asks for the token and keeps it in the OS keychain.
codex mcp add tideways --env TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-serverThe Codex CLI, IDE extension and app share this entry in ~/.codex/config.toml.
Add to the client's MCP configuration (Cursor: ~/.cursor/mcp.json; Gemini CLI: ~/.gemini/settings.json; either also per project):
{
"mcpServers": {
"tideways": {
"command": "npx",
"args": ["-y", "tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "your-token" }
}
}
}Add to .vscode/mcp.json, or run MCP: Open User Configuration for all workspaces. VS Code asks for the token on first start and stores it.
{
"inputs": [
{ "type": "promptString", "id": "tideways-token", "description": "Tideways API token", "password": true }
],
"servers": {
"tideways": {
"type": "stdio",
"command": "npx",
"args": ["-y", "tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "${input:tideways-token}" }
}
}
}In any setup above, replace npx -y tideways-mcp-server with docker run -i --rm -e TIDEWAYS_TOKEN ghcr.io/abuhamza/tideways-mcp-server (pin a version with :2.0.0). For example:
claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- docker run -i --rm -e TIDEWAYS_TOKEN ghcr.io/abuhamza/tideways-mcp-server"command": "docker",
"args": ["run", "-i", "--rm", "-e", "TIDEWAYS_TOKEN", "ghcr.io/abuhamza/tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "your-token" }Related MCP server: otel-mcp-server
Tool | Answers |
| Which projects, scopes and rate-limit budget does my token have? |
| Which services does a project have, and which of them serve "voucher"? |
| How is the app doing in any window of up to 24 h within the last ~30 days? Totals, layers, top transactions |
| Requests, errors and p95 in 15-minute buckets over up to 30 days |
| Which errors, slow SQL queries or deprecations are open, resolved or ignored? |
| Which individual requests were slow, and where did the time go? |
| Day, week or month report for a past date |
| Configuration problems and code bottlenecks Tideways detected (e.g. N+1 queries) |
All tools except tideways_list_projects take an optional project (name or organization/name).
Environment variables; empty values count as unset. The server does not load .env files.
Variable | Default | Meaning |
| required | API token |
| the token's only project | Default project; with several projects and no default, pass |
| from the token's projects | Organization, to match a plain project name |
| API default | Default environment |
| the project's default service | Default service |
|
| API base URL, https only |
|
| Request timeout in ms, a positive integer up to |
|
|
|
All times are UTC, YYYY-MM-DD HH:mm. The API rate limit is per token and clock hour, shared by all projects.
Tools read the project's default service unless you name one. The API cannot list services; tideways_list_services finds them through open issues, and its search costs one request per service.
Limits of the Tideways API: at most 30 traces per search, history for production and the default service only, issues 10 per page, and no trace filter by bottleneck (an N+1 observation's link opens the affected traces in Tideways).
The token is read from the environment and never logged, and trace URLs are returned without query strings. Report vulnerabilities privately as described in SECURITY.md.
npm ci
npm run typecheck && npm run lint && npm run format:check && npm test # the gate
npm run build && npm run inspect # try the tools in the MCP InspectorArchitecture, invariants and how to add a tool: CLAUDE.md. Commits follow Conventional Commits.
Daily, weekly or monthly performance report for a past date: total requests, error rate, p95, top 20 transactions by impact and a timeline. Use to compare days or weeks. A period that has not ended covers only its finished hours (pendingBuckets > 0), and today has no data until it ends; compare such periods per day or use tideways_get_performance_summary. Covers production and the project's default service only; for another environment or service use tideways_get_performance with end and minutes=1440 (one day per call).
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Day to report, "YYYY-MM-DD". For week the API uses the Monday of that week, for month the 1st. | |
| detail | No | "concise" (default) returns a trimmed summary. "full" also includes the unmodified API response under "raw"; it can be very large. | concise |
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| granularity | No | day |
| Name | Required | Description |
|---|---|---|
| raw | No | Unmodified Tideways API response; present only when detail is "full". |
| report | Yes | |
| project | Yes | |
| timeline | Yes | Hourly (UTC) for a day; daily (UTC date, max p95) for a week or month. The first and last days can be partial because the report follows the organization's calendar |
| dateRange | Yes | Report boundaries in the organization's local calendar (timeline keys are UTC) |
| transactions | Yes | Top 20 transactions by impact |
| pendingBuckets | Yes | Hours of the period not aggregated yet (zero-filled by the API, left out); when > 0, report totals cover only part of the period |
| transactionCount | Yes | Transactions in the full report; only the top 20 by impact are listed, detail "full" has all under raw.transaction_report |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, idempotent profile, and the description adds real behavioral depth beyond that: unfinished periods return only completed hours (pendingBuckets > 0), today has no data until it ends, and the tool is scoped to production and the project's default service. These are non-obvious constraints that would otherwise cause silent misinterpretation of results.
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 report contains, then edge-case caveats, then sibling routing. Dense but every clause carries information; the final routing sentence is long but earns its length by naming exact parameters for the alternative.
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. Combined with the annotations and 75% schema coverage, the description supplies everything else an agent needs: payload contents, period-edge behavior, environment/service scope, and the exact escape hatch for other scopes.
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 75% and the description reinforces it by mapping the day/week/month choice onto period semantics and explaining that unfinished periods are truncated. It does not directly explain the granularity enum or the detail=full size warning, but it adds interpretive meaning for the date argument that the schema alone does not convey.
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 (performance report for a past date) and enumerates the exact payload the agent gets: total requests, error rate, p95, top 20 transactions, timeline. An agent can distinguish it from tideways_get_performance and tideways_get_performance_summary 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?
Explicitly names alternatives with the conditions that select them: use tideways_get_performance_summary for unfinished periods, and tideways_get_performance with end plus minutes=1440 for another environment or service. It also states the intended use case ('to compare days or weeks'), so both when and when-not are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Automatic findings Tideways made for a project: PHP configuration problems (e.g. OPcache buffers, timeouts) and code bottlenecks detected in traces (e.g. N+1 queries, sleep, waits). Use for a quick health check or optimization ideas. Findings do not name the affected requests, and the API cannot filter traces by bottleneck: give the user the link, whose page in the Tideways UI lists recent affected traces. Do not infer N+1 queries from slow-SQL issues.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| service | No | Service, e.g. "web" or "worker". Defaults to the configured service, else the project's default service. A project can have several services; tideways_list_services lists them. When results come back, an unknown name fails with an error. | |
| environment | No | Environment, e.g. "production" or "staging". Defaults to the configured environment, else production; criteria.environment (traces: each trace's environment) shows which was used. When results come back, an unknown name fails with an error. |
| Name | Required | Description |
|---|---|---|
| project | Yes | |
| criteria | Yes | |
| observations | Yes |
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.
Performance of any window of 1-1440 minutes ending at "end" (default now) within the last ~30 days: totals (requests, error rate, p95/median/average response time, time per layer), the top 20 transactions by impact, and a timeline. Older windows return zeros; use tideways_get_history for them. For 15-minute trends over 30 days use tideways_get_performance_summary.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Last minute included, "YYYY-MM-DD HH:mm" in UTC. Defaults to now. | |
| detail | No | "concise" (default) returns a trimmed summary. "full" also includes the unmodified API response under "raw"; it can be very large. | concise |
| minutes | No | Window length in minutes (max 1440 = 24h). Above 60 the timeline is downsampled to at most 60 points. | |
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| service | No | Service, e.g. "web" or "worker". Defaults to the configured service, else the project's default service. A project can have several services; tideways_list_services lists them. When results come back, an unknown name fails with an error. | |
| environment | No | Environment, e.g. "production" or "staging". Defaults to the configured environment, else production; criteria.environment (traces: each trace's environment) shows which was used. When results come back, an unknown name fails with an error. |
| Name | Required | Description |
|---|---|---|
| raw | No | Unmodified Tideways API response; present only when detail is "full". |
| totals | Yes | |
| project | Yes | |
| criteria | Yes | What Tideways actually queried. Times are UTC "YYYY-MM-DD HH:mm". |
| timeline | Yes | |
| transactions | Yes | Top transactions by impact; the API returns at most 20 |
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 structurally. The description adds genuinely new behavior: the ~30-day retention limit where older windows silently return zeros rather than erroring. It does not discuss auth or rate limits, but for a read tool with full annotation coverage that is acceptable.
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 dense sentences, front-loaded with the core scope, then the returned data, then the routing constraints. No filler and nothing buried.
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 (return shape need not be described), full annotation coverage, and 100% parameter documentation, the description only needs to add scope and routing — which it does completely for a 6-parameter read 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 description coverage is 100%, so the baseline is 3 and the schema already explains end, minutes, detail, project, service, and environment in detail. The description restates the window range and "end" default but adds no syntax or semantics beyond what the schema carries.
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?
Opens with a specific verb+resource+scope (performance metrics over a 1-1440 minute window ending at "end") and enumerates the payload: totals, top 20 transactions by impact, and a timeline. It explicitly differentiates itself from two named siblings, so an agent can route 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?
States both boundaries: windows older than ~30 days return zeros and should use tideways_get_history, while 15-minute trends over 30 days belong to tideways_get_performance_summary. This is explicit when-to-use and when-to-use-an-alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requests, errors and p95 response time in 15-minute buckets for the last hours hours (up to ~30 days), with totals. Use for trends, before/after comparisons and spotting incidents. For per-minute detail and top transactions use tideways_get_performance.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | How many hours back to include (max 744 = 31 days). The API always returns ~30 days. | |
| detail | No | "concise" (default) returns a trimmed summary. "full" also includes the unmodified API response under "raw"; it can be very large. | concise |
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| service | No | Service, e.g. "web" or "worker". Defaults to the configured service, else the project's default service. A project can have several services; tideways_list_services lists them. When results come back, an unknown name fails with an error. | |
| environment | No | Environment, e.g. "production" or "staging". Defaults to the configured environment, else production; criteria.environment (traces: each trace's environment) shows which was used. When results come back, an unknown name fails with an error. |
| Name | Required | Description |
|---|---|---|
| raw | No | Unmodified Tideways API response; present only when detail is "full". |
| totals | Yes | |
| window | Yes | |
| buckets | Yes | 15-minute buckets, oldest first; a bucket keyed 12:00 covers 12:00-12:14 UTC |
| project | Yes | |
| criteria | Yes | What Tideways actually queried. Times are UTC "YYYY-MM-DD HH:mm". |
| pendingBuckets | Yes | Most recent buckets Tideways has not aggregated yet (zero-filled by the API), left out |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld. The description adds real behavioral detail beyond them: 15-minute bucket granularity, an effective ~30-day window, and that totals are included. It does not discuss rate limits, auth, or result ordering, so it is strong rather than complete.
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 filler, and the core content (metrics, granularity, window) is front-loaded before the routing guidance to the sibling tool. Every clause 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?
An output schema exists, so return values need not be explained; annotations cover the safety profile; and the schema fully documents five parameters. The description supplies the granularity, window cap and routing context an agent needs to choose and call this 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 description coverage is 100%, so the schema already documents every parameter including hours, detail, project, service and environment. The description only echoes the hours window and bucket size, adding no syntax or default semantics beyond what the schema states. 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+resource plus the exact payload: requests, errors, p95 response time in 15-minute buckets with totals. It also explicitly distinguishes itself from tideways_get_performance by granularity and feature set, so an agent can separate the two 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 intents, and the second sentence names the alternative (tideways_get_performance) with the condition that selects it (per-minute detail, top transactions). This is explicit when-to-use plus a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List error, slow-SQL or deprecation issues of a project, newest occurrence first, 10 per page. Use to find what is failing or slow and how often. One type and one status per call. Lists issues seen in the default service of one environment. There is no time filter; use lastOccurred to judge recency.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number; 10 issues per page | |
| type | No | error = exceptions and fatal errors, slowsql = slow SQL queries, deprecated = deprecations | error |
| detail | No | "concise" (default) returns a trimmed summary. "full" also includes the unmodified API response under "raw"; it can be very large. | concise |
| status | No | open (default) = unresolved; resolved, ignored and not_error are triaged states; "new" currently returns the same list as "open". There is no "all"; call once per status you need. | open |
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| environment | No | Environment, e.g. "production" or "staging". Defaults to the configured environment, else production; criteria.environment (traces: each trace's environment) shows which was used. When results come back, an unknown name fails with an error. |
| Name | Required | Description |
|---|---|---|
| raw | No | Unmodified Tideways API response; present only when detail is "full". |
| issues | Yes | |
| hasMore | Yes | True when the page is full; request the next page for more. The API reports no total. |
| project | Yes | |
| criteria | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a read-only, idempotent, non-destructive open-world read, and the description layers on behavior they don't cover: default-service scoping, newest-occurrence-first ordering, 10-per-page paging, absence of any time filter, and that an unknown environment name fails with an error. It also warns that detail=full can be very large.
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?
Four dense sentences, front-loaded with purpose, then ordering/paging, then filtering constraints, then the recency caveat. No sentence is filler and nothing needs to be read twice.
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; the description covers the operational facts an agent needs (pagination, sort order, per-call filter limits, defaults, error on unknown environment). Nothing material is missing for a 6-param, all-optional listing 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%, so the baseline is 3, but the description adds real semantics beyond the schema: one type and one status per call (no combined filtering), and that results are limited to the default service of one environment. That meaningfully clarifies how the filters interact.
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 opens with a specific verb+resource and scope: 'List error, slow-SQL or deprecation issues of a project,' plus ordering and page size. The 'issues' resource is clearly distinct from the trace/observation/performance siblings, 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?
'Use to find what is failing or slow and how often' gives a clear use case, and the constraints (one type and one status per call, no time filter, use lastOccurred for recency) steer invocation well. It stops short of naming an alternative tool or a when-not-to-use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the projects, scopes and rate-limit status of the configured Tideways API token. Call this first when unsure which project to use, or after a scope or unknown-project error.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| scopes | Yes | Token scopes: metrics (performance, summary, history), traces, errors (issues, observations) |
| projects | Yes | |
| rateLimit | Yes | Rate-limit headers from the last counted request (null until another tool has made a request in this session; any data call, e.g. tideways_get_observations, fills it). The hourly limit is shared by all projects of the token. |
| organization | Yes | The token's organization (null if its projects span several) |
| tokenExpired | Yes | |
| defaultProject | Yes | Project used when a call omits "project" (null if none can be chosen) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is returned and when this tool helps recover from token/scope errors, though it does not describe pagination or output structure.
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 tightly written sentences front-load the purpose and then the usage trigger. Every sentence adds information without repetition or 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 an output schema present and no parameters, the description only needs to establish purpose and routing. It does that completely: what is listed, why it matters, and when to call it.
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 there are no parameter semantics to explain. The description appropriately focuses on the token context and result scope rather than inventing parameter details.
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: list the projects, scopes, and rate-limit status available to the configured API token. That is enough to distinguish it from siblings such as tideways_list_services or 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?
It gives clear trigger conditions: call this first when unsure which project to use, or after a scope or unknown-project error. It does not name a sibling alternative for cases where the project is already known, so it falls short of the explicit alternative-routing seen in a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the services of a project (web, APIs, workers, CLI) named by its open issues, the default service first. Call it when the user names an app, API or worker that is not a project, or a transaction that tideways_search_traces does not find in the default service, with "search" set to one word of it: each service is searched for that word and the services are sorted by matching traces, so the first ones serve it. Costs 3 requests, plus 1 per service searched: at most 30, and no more than a tenth of the hourly rate limit. Only services named by the newest open issues are listed; the Tideways UI service selector lists all.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | One whole word of the app, API, worker or transaction to find (e.g. "voucher"). Searches the traces of each service for it (one request per service: at most 30 services, and no more than a tenth of the hourly rate limit) and sorts the services by matching traces. | |
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| environment | No | Environment, e.g. "production" or "staging". Defaults to the configured environment, else production; "environment" in the result shows which was used. When results come back, an unknown name fails with an error. |
| Name | Required | Description |
|---|---|---|
| search | No | Present only with "search" |
| project | Yes | |
| services | Yes | Services named by the newest open errors, slow SQL queries and deprecations (first page of each), plus the default service; other services are missing, and the Tideways UI service selector lists all. Sorted default first, then by issues; with "search", by matchingTraces. |
| environment | Yes | Environment whose issues were read |
| defaultService | Yes | The project's default service, read when no service is passed or configured |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/no-destructive, so the bar is lower, but the description goes further with a request-cost model ('Costs 3 requests, plus 1 per service searched: at most 30, and no more than a tenth of the hourly rate limit') and an important completeness caveat ('Only services named by the newest open issues are listed; the Tideways UI service selector lists all'). It omits nothing critical, though it doesn't mention error behavior for the environment (@schema covers 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?
Purpose and trigger are front-loaded, and every clause carries information (cost, caveat, ordering). It is dense and somewhat comma-chained ('..., with "search" set to one word of it: each service is searched...'), which costs a little readability, but no sentence is 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?
An output schema exists, so return values need not be explained, and the description still covers cost, ordering, default service, listing limitation, and trigger conditions. Nothing an agent needs in order to select and call this tool 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 baseline is 3, and the description adds value beyond it by tying the search parameter to behavior: 'with "search" set to one word of it: each service is searched for that word and the services are sorted by matching traces, so the first ones serve it.' That explains why the parameter exists and how results are ranked, which the schema alone 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?
Opens with a specific verb+resource and scope: 'List the services of a project (web, APIs, workers, CLI) named by its open issues, the default service first.' This tells the agent exactly what comes back and in what order, and it names tideways_search_traces, so it is distinguishable from siblings.
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: 'Call it when the user names an app, API or worker that is not a project, or a transaction that tideways_search_traces does not find in the default service.' It also names an alternative (the Tideways UI service selector) and explains how it differs, which is when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find individual request traces (at most 30 per call, newest first unless sortBy is set) with response time, memory, bottlenecks and the slowest layers. Use to investigate specific slow or failing requests; filter by text, time window and response time.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Latest trace time (inclusive), "YYYY-MM-DD HH:mm" UTC; needs "from" as well | |
| from | No | Earliest trace time, "YYYY-MM-DD HH:mm" UTC; needs "to" as well | |
| detail | No | "concise" (default) returns a trimmed summary. "full" also includes the unmodified API response under "raw"; it can be very large. | concise |
| search | No | One whole word from the transaction name or URL path (e.g. "checkout"), matched against transaction, host and URL tokens. Several words match any of them and widen the result. | |
| sortBy | No | response_time = slowest first, memory = highest first; omit for newest first. Without from/to, sorted results span all retained traces (~30 days). | |
| project | No | Tideways project as "project" or "organization/project". Defaults to the defaultProject that tideways_list_projects reports; call it for valid names. | |
| service | No | Service, e.g. "web" or "worker". Defaults to the configured service, else the project's default service. A project can have several services; tideways_list_services lists them. When results come back, an unknown name fails with an error. | |
| environment | No | Environment, e.g. "production" or "staging". Defaults to the configured environment, else production; criteria.environment (traces: each trace's environment) shows which was used. When results come back, an unknown name fails with an error. | |
| withCallgraph | No | true = only traces that have a full callgraph (profile) | |
| maxResponseTimeMs | No | ||
| minResponseTimeMs | No |
| Name | Required | Description |
|---|---|---|
| raw | No | Unmodified Tideways API response; present only when detail is "full". |
| count | Yes | |
| traces | Yes | |
| project | Yes | |
| limitReached | Yes | True when 30 traces came back, the API maximum: narrow the time window or change sortBy to see others |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive. The description adds genuinely useful traits: a hard cap of 30 results per call and a default ordering (newest first unless sortBy is set). It does not mention pagination or how to retrieve results beyond the cap, so it is not 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?
Two front-loaded sentences: the first covers output and the 30-cap/ordering constraint, the second covers usage and filters. 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 an output schema present, return values need not be re-explained, and the description still supplies the important operational details (result cap, ordering). For an 11-parameter, all-optional search tool this is sufficient, though the tie-in between project/service defaults and the sibling list tools is left entirely to 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 82%, so parameters are already well documented for defaults, formats and enum values (detail, sortBy). The description only restates the filter dimensions at a high level and adds no syntax or edge-case meaning 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+resource (find individual request traces) plus what it returns (response time, memory, bottlenecks, slowest layers). It is clearly distinguishable from the aggregate siblings like 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?
'Use to investigate specific slow or failing requests' gives a clear use context, supplemented by the filter dimensions (text, time window, response time). It never explicitly names the aggregate alternatives to use instead when a summary is wanted, so it falls short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0tideways_get_historytideways_get_observationstideways_get_performancetideways_get_performance_summarytideways_list_issuestideways_list_projectstideways_list_servicestideways_search_tracesScored across 8 tools
The three performance-reporting tools (get_performance, get_performance_summary, get_history) overlap in surface area, but the descriptions carefully delimit each: per-minute detail vs 15-minute trend buckets vs daily/weekly/monthly historical reports. The list_* tools target clearly different resources (projects, services, issues), and search_traces and get_observations are distinct enough.
All tools share the tideways_ prefix and follow a consistent verb_noun pattern (list_projects, list_services, list_issues, search_traces, get_performance, get_history, get_observations). get_performance_summary is a minor variant on the same verb but still readable and predictable.
Eight tools is well-matched to an APM/observability server, covering projects, services, performance, issues, traces, history and observations without redundancy. Each tool earns its place with a distinct investigative role.
The surface covers the main observability lifecycle: discovering projects/services, listing issues, inspecting traces, and pulling performance/history/observations. Minor gaps exist (e.g. no issue detail/status-update tool, no explicit environment listing), but agents can work around these with the given tools.
Ask your AI cost, runway, and guardrails from your real AtlasBurn data — read-only.
Ask about your Agentio campaigns, Creator deals, and performance on YouTube and Meta. Read-only.
Ask your accounts-receivable portfolio anything. Read-only, scoped to your account.
AI access to Hitsteps analytics, live visitors, uptime, goals, alerts, and chats.
