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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds the key behavioral fact that both ranges run through the same aggregation and the result is a delta. It leaves default behavior for null range boundaries unspecified, but it still meaningfully exceeds what annotations alone convey.

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 compact and front-loaded: it states the purpose first, then the mechanics, then concrete use cases. Every sentence earns its place with no redundant filler.

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 9 optional parameters, and the description does not specify the sign/direction of the delta (range A minus range B vs. range B minus range A) or what happens when range boundaries are left null. The schema and output schema cover structure, but these ambiguities could prevent a correct first call.

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 the baseline is 3. The description reinforces that the same aggregation is applied to both ranges and that filters apply to both, but it adds no parameter-level detail beyond what the schema already documents.

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 specific verb and resource: 'Compare aggregated LLM usage metrics between two time windows.' It also names the unique outcome, returning a delta, which clearly differentiates it from single-window siblings like get_llm_usage.

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 gives concrete use cases: 'this week vs last week' and 'before/after a deploy.' It does not explicitly name alternative tools or state when not to use this tool, but the provided context is clear enough for an agent to select it appropriately.

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?

Annotations already cover the read-only, idempotent, non-destructive profile, so the safety burden is met. The description adds that results include detailed error content and LLM-specific information, but it does not describe how errors are selected, whether the output is sorted, or how the time-range and service filters interact with error detection.

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 short, front-loaded with the main action, and its second sentence provides useful detail. It avoids fluff, though it could have used one sentence to clarify its relationship with similar sibling tools.

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?

With a full output schema, rich annotations, and fully documented parameters, the core calling context is covered. However, the description is incomplete in guiding an agent through the large sibling set, especially when search_traces and error-specific investigation tools exist.

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 each parameter already has a meaningful description and default value. The tool description adds no parameter-level information beyond indicating that the returned traces contain error details, so the baseline score of 3 applies.

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 finds traces with errors and lists what is included (error messages, stack traces, LLM-specific information). This gives it a distinct purpose relative to the generic search_traces sibling, though it does not explicitly name a sibling for comparison.

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 is given about when to use this tool versus search_traces, investigate_error_spike, or get_trace. The intended usage is only implied by the tool's name and brief description.

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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's main job is to clarify semantics. It does that by specifying that 'expensive' means token usage rather than monetary cost, and it implies descending ordering by token count. It doesn't discuss pagination or limits, but the output schema and parameter defaults cover much of that.

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 two short sentences with the core operation front-loaded and the use case immediately after. There is no filler, repetition of schema details, or irrelevant context.

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?

With an output schema present and annotations covering safety and idempotency, the description plus structured data give an agent what it needs to call the tool correctly. It adds the essential ranking-by-token-usage context and intended use cases; minor details like default limit are already captured in the schema.

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 already has type, default, and filter semantics documented. The description itself adds no parameter-level information, so it provides no value beyond the schema, which makes the baseline 3 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 opens with 'Find traces with highest LLM token usage,' which names a specific verb, resource, and ranking criterion. This clearly distinguishes the tool from latency-oriented siblings like get_llm_slow_traces and from generic trace/search tools.

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 explicitly says it is 'Useful for cost optimization and identifying inefficient prompts,' giving clear intended usage contexts. It does not explicitly name alternatives or exclusion conditions, but the use case guidance is strong enough for an agent to decide when to invoke this tool.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the specific metrics analyzed, which is useful behavioral context. However, it doesn't disclose aggregation behavior, time window defaults, or whether results are grouped, which would add value 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?

The description is concise and front-loaded with the core purpose, followed by a compact list of metrics. The two-sentence structure is efficient, though the second sentence is a list that could arguably be more integrated. No wasted words.

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 read-only stats tool with full schema coverage and an output schema, the description is largely complete. It covers what the tool does and what metrics it returns. It could be more complete with explicit time-window behavior or grouping semantics, but the annotations and schema cover the essential context.

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 the schema already documents all parameters. The description adds the model_name example and metric context, but doesn't add meaning beyond the schema for start_time, end_time, or service_name. Baseline 3 is appropriate when the schema does the heavy lifting.

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's purpose: getting detailed performance statistics for a specific LLM model, and enumerates the specific metrics (request count, latency percentiles, token usage, error rates, finish reason distributions). This distinguishes it from siblings like get_llm_usage (usage-focused) and get_llm_slow_traces (trace-focused).

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 context (analyzing a specific model's performance) but does not explicitly state when to use this tool versus alternatives like get_llm_usage, get_session_stats, or get_llm_slow_traces. The sibling list provides context, but the description itself lacks explicit routing guidance.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds 'slowest ... by duration' which implies an ordering behavior not present in annotations, but it stops short of explaining sorting direction, default time windows, or other behavioral details.

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 short and front-loaded: the first sentence states the core purpose, and the second provides practical context. Both sentences earn their place, though the second sentence is somewhat generic and could be more specific about the tool's differentiating value.

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 optional parameters, a full schema, output schema, and annotations that cover read-only behavior. The description, while brief, is sufficient for an agent to understand the tool's primary function and call it correctly. The main missing piece is differentiation from similar siblings, but that is more of a usage-guidelines gap.

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 parameter is already documented. The description adds no additional meaning about parameters such as time filtering, service_name, or model filters; it only refers to duration generally. Baseline 3 is appropriate given the rich 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 a specific verb ('Find'), resource ('LLM traces'), and criterion ('by duration', 'slowest'). It is unambiguous about what the tool does, but it does not explicitly contrast with close siblings like get_llm_expensive_traces or search_traces, so it falls short of full sibling differentiation.

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 gives a general use case ('performance optimization and identifying latency bottlenecks') which implies when the tool is useful, but it does not explicitly state when to use it versus alternatives or provide exclusions. No alternative tools are named.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the time-period aggregation and breakdown context, which is useful, but does not disclose any additional behavioral traits such as how limit affects aggregation or whether empty time ranges return empty results.

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 short sentences with no filler. The core action and scope are front-loaded, and the breakdown mention is the only supporting detail—every word earns its place.

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?

With a full input schema, rich annotations, and an output schema, the structured context covers invocation details well. The description is sufficient for a simple read-only aggregation tool, though it would be stronger with an explicit pointer to the closest sibling 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 seven parameters are already documented in the schema. The description's mention of time period and breakdowns does not add meaningful parameter detail beyond what the schema provides, so the baseline of 3 applies.

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 action ('Get aggregated LLM usage metrics'), the resource ('token counts'), and the time-period scope, and adds that breakdowns by model and service are included. It is specific enough to distinguish it from trace-level siblings like get_llm_expensive_traces, though it does not explicitly contrast it with get_llm_model_stats.

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 gives no guidance on when to use this tool versus the many sibling tools, no exclusions, and no alternative recommendations. With siblings like get_llm_model_stats and get_llm_expensive_traces, the agent is left to infer the intended use case.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar for description-added context is lower. The description adds valuable behavioral disclosure by warning that 'real-world adoption of these two attributes is still thin' and that the tool 'may often return an empty list until more instrumentations populate them.'

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 short sentences with no filler. The core action is front-loaded, the grouping detail is explained precisely, and the sparse-adoption caveat earns its place as important operational guidance.

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?

With a full input schema, an output schema, and safety-related annotations, the description covers the essentials. It also supplies the non-obvious expectation about possible empty results. The only missing context is explicit guidance on when to choose this tool over sibling stats tools, which is not strictly necessary for invoking it correctly.

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 the input schema already documents all five parameters. The description adds no additional parameter-level semantics beyond the grouping concept, so the baseline score of 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 opens with a specific verb and resource: 'Get aggregated performance stats grouped by prompt name and version.' It also reinforces the grouping by naming the concrete span attributes and referencing Langfuse's per-prompt Metrics tab. It does not explicitly distinguish itself from sibling tools, but the grouping and naming make its purpose 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 implies when to use the tool through the Langfuse per-prompt Metrics analogy and the caveat about sparse adoption. However, it never explicitly states when to prefer this tool over alternatives like get_llm_model_stats or get_session_stats, nor does it mention any exclusions.

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?

Annotations already declare read-only, idempoten, and non-destructive behavior, and the description does not contradict them. The description adds useful behavioral detail: it aggregates over every span sharing the conversation ID and lists the statistical categories it produces.

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 first sentence is a crisp front-loaded summary, and the second paragraph is a dense but relevant enumeration of the computed metrics. There is no filler or repetition of schema details.

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?

Combined with the full input schema, output schema, and annotations, the description covers scope, filtering, and the metrics computed. An agent can invoke it with just conversation_id and know what is included; no critical behavior is omitted.

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 paramter already has a clear description. The tool description adds no extra parameter-level detail, so the baseline of 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 uses a specific verb-plus-resource pattern ('Get detailed statistics for a single conversation/session') and then lists the exact computed metrics. This clearly differentiates it from sibling search/list/compare tools, which operate over multiple sessions or traces.

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?

It gives clear scope: one conversation/session identified by gen_ai.conversation.id. It doesn't explicitly name alternatives or state when-not-to-use, but the single-session framing and metric detail tell an agent when this is the right tool.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond annotations: it promises 'all spans with attributes,' flags parsed OTLP LLM data as included, and — via the detail_level parameter — discloses that 'full' retains original behavior while 'summary' elides known-large gen_ai.* fields (input/output messages, system instructions, retrieval documents) and truncates long event-attribute values. No contradiction with 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 front-loaded sentences carry the entire tool purpose with zero filler: the primary action comes first, followed by a single sentence detailing return richness. The detail_level parameter text is longer but every clause earns its place by explaining behavioral consequences (elision targets and truncation behavior). Nothing is redundant with the input 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?

For a point-lookup tool with a full output schema, safety annotations, and 100% schema coverage, the description is nearly complete: it states what is returned, mentions OTLP data specifically, and the detail_level parameter explains the only behavioral switch. The one gap is that it does not explicitly route the agent to search_traces for trace discovery when an ID is not known, but this is a minor omission given the tool's straightforward name and signature.

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 the schema already documents both trace_id and detail_level thoroughly. The description adds no format or syntax detail for trace_id beyond 'by trace ID,' and the detail_level parameter description in the schema is already rich. With full schema coverage, the baseline of 3 is appropriate; the description gestures at the parameter's purpose but does not materially extend it.

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 specific verb and resource ('Get complete trace details by trace ID') and clarifies the return content ('all spans with attributes, including parsed Opentelemetry data for LLM operations'). The 'by trace ID' framing makes this a point-lookup tool, clearly distinct from siblings like search_traces and get_llm_usage. The 'complete... all spans' language positions it precisely against the search/list siblings.

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 context is implied rather than explicit: the agent can infer 'use this when you already have a trace ID and want full details,' but the description never says when not to use it or names an alternative such as search_traces for discovery. The detail_level parameter does provide conditional guidance ('for callers that don't need full prompt/completion bodies'), which earns partial credit, but no explicit when/when-not routing exists.

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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the lower bar is appropriate. The description adds meaningful behavioral context beyond annotations: it is on-request/pull-based, not a push alert, and it performs a comparative analysis rather than a simple fetch. It does not discuss rate limits or auth, but nothing in the context suggests those are needed.

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 two compact sentences with the core purpose front-loaded. The second sentence earns its place by giving invocation guidance and an explicit alternative. There is no redundancy or filler; even the SigNoz reference is a brief provenance cue that helps an agent recognize the expected behavior.

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?

With an output schema present and full parameter documentation in the input schema, the description does not need to restate return values or syntax. It provides the selection context, the pull-based behavior, and the trigger condition. It could more explicitly differentiate from compare_time_windows, but that is a minor gap given the strength of the structured fields.

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?

The input schema has 100% parameter description coverage, so the baseline is 3. The description adds a useful high-level framing of comparing windows and ranking contributors, but it does not add parameter-level detail beyond what the schema already provides. That is acceptable because the schema carries the load here.

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 names a specific task (investigate an LLM cost spike), a concrete method (compare recent window against a baseline), and a distinct output (ranked contributors). It clearly separates itself from raw usage polling via get_llm_usage and from error-focused investigation via investigate_error_spike.

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?

It gives an explicit trigger condition: 'Call this when you suspect (or want to check for) a cost increase'. It also names the alternative approach it replaces ('rather than polling get_llm_usage by hand') and clarifies it is pull-based, not a push alert, so an agent knows when it is appropriate to invoke.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by explaining the spike detection criteria (absolute floor and relative multiplier), which prevents misuse on tiny samples. No contradiction with 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 with no fluff. The primary purpose is front-loaded, and the nuance about spike criteria is concisely added. Every sentence earns its place.

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 the tool's complexity (9 params, 100% schema coverage) and presence of an output schema, the description covers the core logic well. It could mention how the output is structured or when to prefer this over siblings, but those are covered elsewhere or optional. Overall, sufficient for correct invocation.

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 parameters are already documented. The description adds marginal value by referencing the spike criteria, but it doesn't explicitly map to the min_error_count_increase and rate_multiplier_threshold parameters beyond what the schema states. 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 a specific verb ('investigate') and resource ('error-rate spike'), and explains the action: compare a recent window against a baseline and rank contributors. It distinguishes itself from sibling tools like investigate_cost_spike by focusing on error rates, and from compare_time_windows by ranking contributions.

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 for investigating error spikes but does not explicitly state when to use this tool versus alternatives like compare_time_windows or search_traces. No exclusions or alternative routing are provided, leaving the agent to infer context from the name and sibling list.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds that results are limited to models in use and include usage stats, but it discloses no further behavioral traits such as trace-based analysis, result limits, or aggregation details.

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 short and front-loaded, with the core action in the first sentence. The second sentence is slightly redundant but adds a discovery-oriented framing, so it isn't wasted.

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 rich annotations, a 100%-documented optional parameter set, and an output schema, the description provides enough context for invocation. It could be more explicit about sibling tool distinctions and the trace-derived nature of the results, but nothing critical is missing.

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%: all five parameters (limit, end_time, start_time, service_name, gen_ai_system) are already described inline with types, defaults, and examples. The tool description adds no parameter-specific meaning, which is acceptable because the schema carries the weight.

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 specific verb ('List'), resource ('LLM models'), and scope ('all ... being used'), and adds that it returns usage statistics. It is not a tautology, though it doesn't explicitly distinguish itself from the sibling tool get_llm_model_stats.

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 second sentence ('Discovers what models are deployed and tracks their usage patterns') gives clear context for when this tool is useful. It doesn't name alternatives or state exclusions, so it stops short of a 5.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false bir, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it reveals the internal filtering mechanism (traceloop.span.kind == tool) and the aggregation behavior (grouped by tool name with usage statistics), which helps the agent understand what the result represents.

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 two short sentences, with the core purpose front-loaded and no filler. The grouping/usage-statistics detail earns its place and is not redundant with the schema or annotations.

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 the tool's relative simplicity, the output schema presence, and fully described parameters, the description is mostly complete. It explains the key behavioral detail (span kind filtering) and the return shape (grouped with usage statistics). The only gap is explicit guidance on when to choose this over related sibling tools.

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 parameter already has a clear description. The tool description does not add parameter-specific semantics beyond what the schema provides, which fits the baseline of 3 for full 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 names a specific verb and resource ('List all LLM tools being used'), identifies the exact span condition (traceloop.span.kind == tool), and states the output grouping ('grouped by tool name with usage statistics'). This clearly distinguishes it from sibling tools like list_llm_models.

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 when to use the tool ('Discovers which tools/functions LLM applications are calling'), but it does not explicitly compare it to alternatives such as list_llm_models or get_llm_usage, nor does it state when not to use it. Usage guidance is present but only implicit.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the return format ('JSON string with list of services') and the scope 'all available services,' which are useful behavioral details 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?

The description is two short, front-loaded sentences with no filler. The core action is stated first, and the return type is provided in a clearly separated line. Every sentence earns its place.

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 zero-parameter, read-only listing tool with rich annotations and an output schema, the description is sufficient. It states what is listed, the backend scope, and the return format. There are no missing pieces an agent would need to invoke this tool correctly.

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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed since the input schema is empty and schema coverage is 100% by definition.

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 specific action ('List') and resource ('all available services in the OpenTelemetry backend'). It clearly distinguishes this from sibling tools like list_llm_models or list_sessions by specifying services in the OpenTelemetry backend. The scope is explicit and unambiguous.

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 provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or conditions that would select this tool over sibling list tools. The intended usage is only implied by the name and one-line action.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by explaining the grouping mechanism, the OTel semantic convention, and the per-conversation metrics produced. No contradiction with 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 concise sentences with the primary action front-loaded. The OTel convention explanation earns its place by clarifying why this attribute is meaningful, and there is no redundant restatement of 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?

With fully documented parameters, rich annotations, and an output schema, the description is nearly complete. It clearly explains the grouping key and intended use case; a brief cross-reference to get_session_stats would make it fully 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%, so the schema already documents all five parameters. The description adds no parameter-specific meaning beyond identifying the grouping key, so the baseline 3 applies.

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 action and resource: list conversations/sessions grouped by gen_ai.conversation.id, and specifies the surfaced outputs (span counts, token usage, time bounds). This clearly distinguishes it from trace- and span-oriented sibling tools.

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 says it is 'useful for understanding multi-turn conversation activity,' which implies when to use it, but it does not name alternatives or state when not to use it (e.g., versus get_session_stats). Guidance is present but only implied.

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?

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds the key behavioral trait of returning individual spans rather than grouped traces, which is not fully encoded in the annotations. No contradiction with the annotations is present.

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 deliver the purpose, the differentiating sibling, and a concrete use case without redundancy. Every sentence earns its place and the key distinction is front-loaded.

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 schema is rich, every parameter is described, annotations already establish the safety profile, and an output schema exists. The description provides the selection context that the structured fields cannot, making the definition complete for correct invocation.

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?

All 13 parameters are fully documented in the schema, so the baseline applies. The description's tool-call filter example is useful context, but it does not add substantial parameter semantics beyond the schema's detailed field descriptions.

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 specific verb-resource pair ('Search for individual OpenTelemetry spans') and immediately differentiates itself from search_traces by the returned granularity. This tells an agent exactly what the tool does and how to distinguish it from its closest sibling.

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?

It explicitly names the alternative (search_traces) and explains the condition that chooses this tool: individual spans rather than grouped traces, for analyzing specific operations or filter-matching characteristics. This is clear when-to-use guidance with a concrete example.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the filter-system feature but does not disclose any additional behavioral traits such as default time ranges, pagination behavior, or result ordering; this is acceptable but not a strong contribution.

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 short and front-loaded with the core purpose. The second sentence about simple versus advanced filters is useful, though it is somewhat generic and could have been replaced with more specific guidance.

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 the rich input schema, full schema coverage, output schema, and comprehensive annotations, the description is adequate for invoking the tool. It could be more complete by clarifying the default search window or how results are returned, but those gaps are partially filled by the schema and output schema.

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 the schema already documents all 13 parameters in detail. The description's mention of 'simple parameters and advanced generic filter system' adds a useful high-level categorization, but it does not add meaning beyond what the schema already provides.

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 searches OpenTelemetry traces and supports filtering. It is specific about the resource and action, though it does not explicitly differentiate itself from search_spans_tool or call out that get_trace is for single-trace retrieval.

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 mentions that both simple parameters and an advanced generic filter system are supported, which hints at how to choose between those approaches. However, it gives no guidance on when to use this tool versus sibling tools like search_spans_tool, get_trace, or find_errors.

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