query_traces

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

Annotations already cover the safety profile (readOnly, idempotent), and the description adds real behavior: deterministic ordering by start time descending and a keyset pagination contract. It still omits whether the window is inclusive/exclusive and that results are summaries rather than full spans, but it adds meaningful context beyond the annotations.

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, zero filler, with the core purpose and ordering front-loaded before the pagination detail. Every clause carries information an agent needs.

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?

There is no output schema, and the description partially compensates by naming the summary return type and the nextCursor field. Combined with the fully documented input schema, an agent has enough to call it correctly; only window-boundary semantics are left unstated.

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 baseline is 3, but the description adds value by pairing the input 'cursor' with a 'nextCursor' continuation token that exists only in the response, clarifying the pagination loop. It does not restate the limit defaults or service filter semantics, which the schema already handles.

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?

States a specific verb and resource ('List trace summaries'), the scoping condition (UTC time window), and the sort order (start time descending). It is clearly distinct from get_trace (single trace) and list_trace_services, though no sibling is named explicitly.

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?

Usage is only implied: the tool is for browsing traces within a window. There is no explicit when-to-use/when-not-to-use guidance and no pointer to get_trace for full trace detail, which is the obvious companion. The pagination sentence does signal a follow-up call pattern.

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