tempo_search_spans

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

No annotations are provided, so the description carries full behavioral disclosure burden. The description mentions it returns spans across multiple traces and supports filtering, but doesn't disclose key behaviors such as whether it aggregates/fuses spans from different traces into one result, how results are ordered, whether it's read-only, pagination behavior, or how the various filtering dimensions (query, tags, serviceName, spanHasError) interact. Multiple filter parameters coexist without explaining precedence or combination semantics.

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 sentences, efficient and to the point. First sentence states core function and scope. Second sentence adds a use case. No wasted words, but could have used the space to convey more meaningful differentiation and behavioral detail.

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?

This is a complex tool with 13 parameters, nested objects, no output schema, and no annotations. The description is inadequate for this complexity. It doesn't explain the interplay between the many filter dimensions, what the response format looks like (returns spans from multiple traces - but merged into what structure?), or how this compares to sibling tools that also deal with traces and spans. For a tool of this complexity, the description should provide substantially more guidance.

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% and every parameter has a text description in the schema itself. However, the tool has 13 parameters including nested objects (spanAttributes), and the description provides no additional semantic context about how parameters like query, tags, minDuration/maxDuration, and span* filters relate to each other. The description adds modest value (mentions 'filtering' generally) but relies heavily on the schema. Some parameters like minDuration/maxDuration are ambiguous in format (seconds vs ms) while spanMinDuration/spanMaxDuration explicitly state ms.

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 it searches for traces and returns matching spans across multiple traces with filtering. It uses a specific verb+resource (search traces/spans) but doesn't distinguish from sibling tools like tempo_search_traces or tempo_get_trace_spans, which appear closely related. The purpose is clear but ambiguous about how this differs from siblings that share overlapping functionality.

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?

No guidance on when to use this tool vs alternatives. The description says 'useful for finding specific operations across your system' which implies general use but offers no exclusions or comparison with siblings like tempo_search_traces, tempo_get_trace, or tempo_get_trace_spans. Given 5 sibling tools with overlapping purposes, explicit differentiation is needed and absent.

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