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

With no annotations provided, the description carries the full burden. It states what is returned (count, avg/min/max/percentile durations) but omits important behaviors: relationship between limit and query parameters, what happens with no query specified, whether start/end are required in practice, time parsing format, or pagination behavior. For an aggregation tool with 6 optional parameters, this leaves significant uncertainty.

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 concise sentences that front-load the core purpose and then specify return values. Zero filler or redundancy. Efficient and to the point.

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?

For a tool with 6 parameters, no output schema, and no annotations, the description gives a reasonable purpose and mentions the return value shape (count, durations). However, it doesn't cover parameter interactions (query vs tags, start/end formats, limit semantics), which would be valuable for an agent selecting parameters. It's adequate but has clear gaps given the tool's complexity.

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%, so every one of the 6 parameters is documented in the schema itself. The description adds the grouping concept (service/operation/status) which maps to the groupBy enum. However, the description doesn't clarify how query/tags interact, what 'Number of traces to analyze' means for aggregation sampling, or time format expectations, which would add genuine value beyond the schema.

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 clearly states the verb (Get), resource (spans), and action (aggregated statistics grouped by service/operation/status). It distinguishes from siblings like tempo_get_trace and tempo_search_spans by focusing on aggregation rather than retrieval of individual traces or spans. However, it doesn't explicitly name sibling tools as contrasts.

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?

The description implies this is for retrieving aggregated stats versus other tracing tools, but does not explicitly state when to use this versus the sibling tools (tempo_search_spans, tempo_get_trace, etc.). No exclusions or alternative recommendations are given. The grouping dimension gives some hint of usage context, but it's implicit rather than explicit.

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

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 describes what data is returned but says nothing about payload size/volume (complete traces with all spans could be very large), potential performance implications, whether partial data can be returned, or what happens if the trace ID doesn't exist. A 'get complete trace data' tool that returns potentially massive payloads should warn about size/truncation behavior.

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?

The description is a single sentence with zero waste. It efficiently communicates the core purpose and return scope. It could be slightly more structured with usage guidance added, but as-is it is concise and front-loaded with the key action ('Get complete trace data').

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?

The tool requires only one parameter (traceId) with 100% schema coverage and no nested objects, so complexity is low. However, without annotations or an output schema to describe the return payload, and with five sibling tools that overlap in purpose, the description leaves gaps around what distinguishes this from tempo_get_trace_spans and whether trace retrieval has size limits or error behaviors. Adequate but not complete.

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% (the single traceId parameter is described as 'The trace ID to retrieve'). The description adds the semantics that this ID retrieves 'complete trace data' with 'all spans', which provides modest additional value by clarifying the scope of the return. This aligns with the baseline 3 for high schema coverage.

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 a clear verb+resource combination: 'Get complete trace data by trace ID.' It covers what data is returned ('complete trace data' including 'all spans with full details'). It distinguishes from sibling tools somewhat by emphasizing 'complete trace data' with 'full details', though it doesn't explicitly contrast with tempo_get_trace_spans, which likely retrieves a subset of the same data.

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?

The description implies usage: when you have a trace ID and want complete data. However, it provides no explicit when-to-use guidance or distinctions from siblings like tempo_get_trace_spans (which may be lighter-weight when only spans are needed) or tempo_search_traces (for finding traces by criteria). The distinction between complete trace data and span-specific retrieval is implied but not made explicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It's a read operation (fetching spans), so the readOnly nature is implied but not explicitly stated. The description doesn't disclose pagination limits (traces can have hundreds of spans), whether results are returned in any particular order, or what happens when no spans match the filters. For a potentially large-returning fetch tool with zero annotation coverage, this is a notable gap.

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?

A single, efficient sentence that front-loads the core purpose (get spans from a trace) and then enumerates the filtering dimensions. Zero wasted words, no redundancy with the schema.

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?

Given no output schema, the description might be expected to note the return shape—but for span retrieval this is reasonably self-evident. With 7 parameters, a complex nested 'attributes' object, and no annotations, the description is adequate but doesn't cover behavioral caveats like result limits, ordering, or default filter behavior. It's a minimum-viable description for a moderately complex tool.

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%, so all 7 parameters are documented in the schema itself. The description summarizes the filtering dimensions (service name, span name, duration, attributes, error status) which roughly maps to the parameters. Since coverage is high, baseline 3 applies; the description adds little beyond naming the filter categories, not syntax or interaction rules between filters.

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 a clear verb+resource: 'Get all spans from a specific trace'. The scope is specific (from a trace, not a global search) and the sibling tools like tempo_search_spans (global span search) and tempo_search_traces (trace querying) are differentiated by this trace-scoped focus. It doesn't explicitly name alternatives but the phrase 'from a specific trace' implies the distinction.

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?

The description explains what filtering dimensions are available (service, span name, duration, attributes, error status) which implies when this is appropriate—when you already have a traceId and want to drill down. However, it does not state any exclusion criteria (e.g., 'use tempo_search_spans for cross-trace filtering') or prerequisites beyond the required traceId being self-evident from the schema.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It doesn't mention anything about read-only status, limits, pagination, error behavior, or what 'convenience' entails concretely. For a trace-query tool with zero annotation coverage, this is a significant transparency gap.

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?

The description is a single efficient sentence that gets to the point quickly with concrete examples. No wasted words, though it could benefit from a brief note on relationship to sibling tools without losing brevity.

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?

The tool has 7 parameters, a nested object (tagFilters), and no output schema, making it moderately complex. The description explains the primary mechanism (tag filter querying) but doesn't address how it differs from the numerous sibling search tools, nor does it explain temporal/duration parameter semantics. Adequate but with clear gaps for a moderately complex tool.

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 coverage is 100%, so the schema documents all 7 parameters. The description adds marginal value by explaining tagFilters usage with examples, but doesn't clarify semantics for start/end time formats, minDuration/maxDuration encoding, or how limit behaves. Baseline 3 is appropriate since the schema already covers parameter basics.

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 clearly identifies this as a convenience method to query traces by tag/attribute filters. It names the resource (traces) and the mechanism (tag filters), with useful examples like user.id and environment. However, it doesn't explicitly distinguish from sibling tools like tempo_search_traces or tempo_search_spans, which could be ambiguous given the sibling set.

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?

The description notes this is a 'convenience method' and gives example filter use cases (sometag, user.id, environment), implying it's for tag-based filtering. However, it provides no explicit when-to-use vs when-not-to-use guidance relative to siblings like tempo_search_traces or tempo_search_spans, leaving the selection decision ambiguous.

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

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the parser normalizes queries automatically and that the default time range is 7 days, which is useful. However, it doesn't disclose behavior like rate limits, what happens on parse failures, whether results are paginated, or whether the legacy tags format still works fully or is deprecated.

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?

The description is three sentences and reasonably tight. It front-loads the core purpose (search traces using TraceQL) and adds key behavioral notes (normalization, default time range). It's compact without being verbose, though the normalization point is partially redundant with the schema's query description which already mentions 'The parser will automatically normalize attribute paths.'

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?

For a 7-parameter search tool with no output schema and no annotations, the description is moderately complete. It covers the core value proposition and default time range. However, given the richness of sibling tools (trace vs span search, tag-based query), and that TraceQL is a specialized query language, the description could explain more about what fields are searchable and how results relate to tempo_get_trace. The schema does carry substantial weight here via the query examples.

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 coverage is 100%, so all 7 parameters are documented in the schema. The description adds the automatic normalization context and the 7-day default, but doesn't go beyond the schema for start/end format details, maxDuration/minDuration units, or limit semantics. The query parameter's rich example set is entirely in the schema, not the description. Baseline 3 is appropriate.

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 clearly states the tool 'Search traces using TraceQL query language', establishes it handles various query syntax formats with automatic normalization. It's distinguished from siblings like tempo_search_spans (searching spans vs traces) and tempo_get_trace (fetching a specific trace by ID). The verb+resource+scope is specific and clear.

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?

The description states it uses TraceQL and handles query normalization, plus a default time range. However, it doesn't explicitly say when to use this vs alternatives like tempo_search_spans or tempo_query_by_tag, nor does it warn against using the legacy tags format. Usage context is implied by the query language mention but lacks explicit alternative guidance.

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