tempo_search_traces

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.