Skip to main content
Glama

Search spans and slow routes

search_traces
Read-only

With no filters: every route and screen with its count, error rate, p50, p95 and slowest dependency. With any filter: matching spans from the backend and the app, or count, avg, p50, p95 and errors with group_by. Use it to find what is slow or failing, then open one with get_trace. Spans are kept 30 days.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_traces"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoText in the span name, any case
opNoLike http.server, http.client, ui.load, app.start, gen_ai, mcp.server
toNoAn ISO time, or how long ago
fromNoAn ISO time, or 30m, 24h, 7d (default 24h)
sortNoFor spans (default recent)
limitNoRows (default 50, overview 25)
rangeNoWindow of the routes overview (default 24h)
routeNo
cursorNonext_cursor from the last answer
sourceNoDefault all
statusNook, error, or one HTTP status like 503
releaseNoOnly this release: 2.0.77+185, 2.0.77 (every build) or package@2.0.77+185
serviceNo
group_byNoCounts and timings per value instead of spans. release and environment also give p75, p90, p99 and time spent
timeseriesNotrue: points over time instead of rows (per minute, error rate, p50, p95), with where releases started
environmentNoOnly this environment, like production ('all' for every one)
min_duration_msNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / release / description
      Previous value: -"Only this release (service version)"New value: +"Only this release: 2.0.77+185, 2.0.77 (every build) or package@2.0.77+185"
  2. Changed5 schema fields changed
    • addedInput schema / properties / environment
      Added value: +{
      +  "description": "Only this environment, like production ('all' for every one)",
      +  "maxLength": 40,
      +  "type": "string"
      +}
    • changedInput schema / properties / group_by / description
      Previous value: -"Counts and timings per value instead of spans"New value: +"Counts and timings per value instead of spans. release and environment also give p75, p90, p99 and time spent"
    • changedInput schema / properties / group_by / enum
      Previous value: -[
      -  "op",
      -  "route",
      -  "service",
      -  "status",
      -  "name"
      -]New value: +[
      +  "op",
      +  "route",
      +  "service",
      +  "status",
      +  "name",
      +  "release",
      +  "environment"
      +]
    • addedInput schema / properties / release
      Added value: +{
      +  "description": "Only this release (service version)",
      +  "maxLength": 60,
      +  "type": "string"
      +}
    • addedInput schema / properties / timeseries
      Added value: +{
      +  "description": "true: points over time instead of rows (per minute, error rate, p50, p95), with where releases started",
      +  "type": "boolean"
      +}
  3. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description only needs to add context. It does add real behavioural facts the annotations lack: the retention window ('Spans are kept 30 days') and the fact that the output shape changes based on whether filters are present. Pagination mechanics are only hinted at through the cursor parameter rather than described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the mode-dependent return shape and ending with the retention caveat and next-step pointer. The parallel 'With no filters: … With any filter: …' construction is efficient, though the sentence fragment style takes a moment to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter read tool with no output schema and no required parameters, the description is unusually complete: it enumerates the returned metrics, explains the filter-driven branching, gives the retention limit, and routes the agent to get_trace. It lacks only coverage of the timeseries mode and pagination, which the agent must recover from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 82%, so the schema already does most of the work and the baseline is 3. The description adds mode-level meaning — that the presence of any filter switches from the routes overview to spans, and that group_by switches to counts and timings — but it says nothing about timeseries, min_duration_ms or cursor behaviour, which appear only in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (spans and routes) and states precisely what is returned in each mode: routes with count, error rate, p50, p95 and slowest dependency when unfiltered, versus matching spans or grouped aggregates when filtered. It also distinguishes itself from the drill-down sibling by name ('then open one with get_trace'), so an agent can separate it from get_trace 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use it to find what is slow or failing, then open one with get_trace' gives a clear entry-point role and an explicit next step in the workflow. It stops short of naming exclusions, such as when to prefer search_logs or search_error_events instead, so the agent must infer boundaries from the sibling list.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources