tracehub-mcp

Overview Schema Source Related Servers Discussions Admin

search_spans_tool

Search individual OpenTelemetry spans by service, operation, duration, errors, LLM provider/model, or tags to analyze specific operations and tool calls.

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).

Args: service_name: Filter by service name operation_name: Filter by operation/span name start_time: Start time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z) end_time: End time in ISO 8601 format min_duration_ms: Minimum span duration in milliseconds max_duration_ms: Maximum span duration in milliseconds gen_ai_system: Filter by LLM provider (e.g., openai, anthropic) gen_ai_request_model: Filter by requested model name (e.g., "gpt-4") gen_ai_response_model: Filter by actual model used (e.g., "gpt-4-0613") has_error: Filter spans with errors tags: Additional tag filters as key-value pairs filters: 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" limit: Maximum number of spans to return (1-1000, default: 100)

Returns: JSON string with span summaries

Example filter to find LLM tool calls: {"field": "traceloop.span.kind", "operator": "equals", "value": "tool", "value_type": "string"}

Input Schema

TableJSON Schema

Name	Required	Description	Default
`tags`	No
`limit`	No
`filters`	No
`end_time`	No
`has_error`	No
`start_time`	No
`service_name`	No
`gen_ai_system`	No
`operation_name`	No
`max_duration_ms`	No
`min_duration_ms`	No
`gen_ai_request_model`	No
`gen_ai_response_model`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the limit range (1-1000, default 100) and the return format ('JSON string with span summaries'), but says nothing about pagination, ordering, or permission/auth requirements for a 13-parameter query tool.

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-loaded summary and the args list is well-organized and justified by 13 undocumented parameters, though the Returns and Example blocks add modest length beyond the essentials.

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?

An output schema exists so return values needn't be spelled out, and the description covers all parameters plus the sibling comparison. It is nearly complete for a read-only search tool, with pagination/ordering behavior the main omission.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does: every one of the 13 parameters is documented with meaning, format (ISO 8601, dotted notation), examples ('gpt-4-0613', openai/anthropic), and the nested filter object's field/operator/value/value_type structure.

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+resource ('Search for individual OpenTelemetry spans') and explicitly differentiates from the sibling search_traces by explaining it returns individual spans rather than grouped traces.

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?

Names the alternative (search_traces) and the condition that selects this tool instead, plus a concrete use case (finding spans with traceloop.span.kind == tool). An agent can route correctly without opening either schema.

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

Deploy Server