Control Plane

Get Trace

get_trace

Read-onlyIdempotent

Fetch one distributed trace by ID (from query_traces) and summarize it: the span tree with each span's duration, service, kind (server: a request the workload received; client: a call it made), method, path, and status; the request ids to match against access and request logs; and the error spans with their messages. Use it to pinpoint WHERE latency or failures sit inside a request path. Very large traces show the first spans in tree order, and error spans are always listed.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`org`	No	Organization slug.
`traceId`	Yes	Trace ID (hex, from query_traces results).

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`data`	No	The full result. Read this, not only the summary.
`details`	No
`summary`	Yes
`nextSteps`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedSep 30, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedInput schema / additionalProperties
```
Removed value: -false
```

changedInput schema / properties / org / description

Previous value: -"Organization slug (lowercase kebab-case). NEVER guess — if the user has not named one, ask. On org-not-found, stop and ask; do not retry variants."New value: +"Organization slug."

removedInput schema / properties / org / maxLength
```
Removed value: -63
```
removedInput schema / properties / org / minLength
```
Removed value: -1
```

removedInput schema / properties / org / pattern

Removed value: -"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"

removedInput schema / properties / traceId / pattern
```
Removed value: -"^[0-9a-fA-F]{1,64}$"
```

changedInput schema / required

Previous value: -[
-  "org",
-  "traceId"
-]New value: +[
+  "traceId"
+]

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

removedOutput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / properties / data / description

Previous value: -"The full machine-readable result — list rows, the resource object, query results. Read THIS, not just the summary."New value: +"The full result. Read this, not only the summary."

addedOutput schema / properties / details
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / nextSteps / description

Removed value: -"Recommended follow-up actions for this task, in order."

removedOutput schema / properties / ok / description
```
Removed value: -"Whether the call succeeded."
```
removedOutput schema / properties / summary / description
```
Removed value: -"One-line summary of the result."
```

AddedAug 14, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond them: large traces are truncated to the first spans in tree order and error spans are always listed, which matters for interpreting results.

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?

Front-loads the verb+resource, then enumerates what the summary contains. Dense but each clause carries information; only the long enumeration of return fields pushes at the boundary of what the output schema could cover.

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 read-only lookup with a full schema and an output schema, the description is largely complete: it explains usage, what is returned, and the truncation/error-listing behavior. Minor gap is that it does not note pagination/scoping for the org parameter, but nothing essential is missing.

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 coverage is 100%, so the schema already documents both org and traceId. The description adds only that the ID originates from query_traces; it adds no format or scoping detail beyond the schema. Baseline 3 applies.

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?

States a specific verb and resource ('Fetch one distributed trace by ID') plus the exact contents returned (span tree, request ids, error spans). It also names its sibling query_traces as the source of the ID, so an agent can distinguish it from other get_* tools.

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?

Explicitly routes the agent: traceId comes 'from query_traces', and the intended use ('pinpoint WHERE latency or failures sit inside a request path') is stated. It gives clear context but no explicit when-not or excluded alternatives.

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

All Control Plane tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.