tracehub-mcp

Overview Schema Source Related Servers Discussions Admin

Search Spans

search_spans_tool

Read-onlyIdempotent

Find individual OpenTelemetry spans by service, operation, LLM model, duration, error, or tag filters. Analyze specific operations or locate spans with target characteristics instead of grouped traces.

Instructions

Search for individual OpenTelemetry spans with optional filters.

Unlike search_traces, this returns individual spans rather than grouped traces, which is useful for analyzing specific operations or finding spans with certain characteristics (e.g., LLM tool calls with traceloop.span.kind == tool).

Input Schema

TableJSON Schema

Name	Required	Description
`tags`	No	Additional tag filters as key-value pairs
`limit`	No	Maximum number of spans to return (1-1000, default: 100)
`filters`	No	Generic filter conditions - list of filter objects with: - field: Field name in dotted notation (e.g., "traceloop.span.kind") - operator: Comparison operator - value: Single value for most operators - values: List of values for "in", "not_in", "between" operators - value_type: Type of value(s) - "string", "number", or "boolean"
`end_time`	No	End time in ISO 8601 format
`has_error`	No	Filter spans with errors
`start_time`	No	Start time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)
`service_name`	No	Filter by service name
`gen_ai_system`	No	Filter by LLM provider (e.g., openai, anthropic)
`operation_name`	No	Filter by operation/span name
`max_duration_ms`	No	Maximum span duration in milliseconds
`min_duration_ms`	No	Minimum span duration in milliseconds
`gen_ai_request_model`	No	Filter by requested model name (e.g., "gpt-4")
`gen_ai_response_model`	No	Filter by actual model used (e.g., "gpt-4-0613")

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	Yes
`spans`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv0.11.0Sep 19, 2026

addedInput schema / properties / end_time / description
```
Added value: +"End time in ISO 8601 format"
```

addedInput schema / properties / filters / description

Added value: +"Generic filter conditions - list of filter objects with:\n- field: Field name in dotted notation (e.g., \"traceloop.span.kind\")\n- operator: Comparison operator\n- value: Single value for most operators\n- values: List of values for \"in\", \"not_in\", \"between\" operators\n- value_type: Type of value(s) - \"string\", \"number\", or \"boolean\""

addedInput schema / properties / gen_ai_request_model / description

Added value: +"Filter by requested model name (e.g., \"gpt-4\")"

addedInput schema / properties / gen_ai_response_model / description

Added value: +"Filter by actual model used (e.g., \"gpt-4-0613\")"

addedInput schema / properties / gen_ai_system / description

Added value: +"Filter by LLM provider (e.g., openai, anthropic)"

addedInput schema / properties / has_error / description
```
Added value: +"Filter spans with errors"
```

addedInput schema / properties / limit / description

Added value: +"Maximum number of spans to return (1-1000, default: 100)"

addedInput schema / properties / max_duration_ms / description
```
Added value: +"Maximum span duration in milliseconds"
```
addedInput schema / properties / min_duration_ms / description
```
Added value: +"Minimum span duration in milliseconds"
```
addedInput schema / properties / operation_name / description
```
Added value: +"Filter by operation/span name"
```
addedInput schema / properties / service_name / description
```
Added value: +"Filter by service name"
```

addedInput schema / properties / start_time / description

Added value: +"Start time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)"

addedInput schema / properties / tags / description

Added value: +"Additional tag filters as key-value pairs"

Changed6 schema fields changedv0.5.0Sep 15, 2026

addedOutput schema / description

Added value: +"Structured response shape for the search_spans tool - see\nSearchTracesResult's docstring for why this is a real model rather than\na bare str."

addedOutput schema / properties / count
```
Added value: +{
+  "type": "integer"
+}
```

removedOutput schema / properties / result

Removed value: -{
-  "type": "string"
-}

addedOutput schema / properties / spans

Added value: +{
+  "items": {
+    "description": "Simplified span summary for list results.",
+    "properties": {
+      "duration_ms": {
+        "type": "number"
+      },
+      "extra_attributes": {
+        "anyOf": [
+          {
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "gen_ai_system": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "is_llm_span": {
+        "default": false,
+        "type": "boolean"
+      },
+      "operation_name": {
+        "type": "string"
+      },
+      "parent_span_id": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "service_name": {
+        "type": "string"
+      },
+      "span_id": {
+        "type": "string"
+      },
+      "start_time": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "status": {
+        "enum": [
+          "OK",
+          "ERROR",
+          "UNSET"
+        ],
+        "type": "string"
+      },
+      "total_tokens": {
+        "anyOf": [
+          {
+            "type": "integer"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null
+      },
+      "trace_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "trace_id",
+      "span_id",
+      "parent_span_id",
+      "operation_name",
+      "service_name",
+      "start_time",
+      "duration_ms",
+      "status"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "count",
+  "spans"
+]

removedOutput schema / x-fastmcp-wrap-result
```
Removed value: -true
```

First observedv0.1.0Sep 12, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds the key behavioral trait of returning individual spans rather than grouped traces, which is not fully encoded in the annotations. No contradiction with the annotations is present.

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

Conciseness5/5

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

Two sentences deliver the purpose, the differentiating sibling, and a concrete use case without redundancy. Every sentence earns its place and the key distinction is front-loaded.

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

Completeness5/5

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

The schema is rich, every parameter is described, annotations already establish the safety profile, and an output schema exists. The description provides the selection context that the structured fields cannot, 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.

Parameters3/5

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

All 13 parameters are fully documented in the schema, so the baseline applies. The description's tool-call filter example is useful context, but it does not add substantial parameter semantics beyond the schema's detailed field descriptions.

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 states a specific verb-resource pair ('Search for individual OpenTelemetry spans') and immediately differentiates itself from search_traces by the returned granularity. This tells an agent exactly what the tool does and how to distinguish it from its closest sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

It explicitly names the alternative (search_traces) and explains the condition that chooses this tool: individual spans rather than grouped traces, for analyzing specific operations or filter-matching characteristics. This is clear when-to-use guidance with a concrete example.

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