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

Annotations declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: it fetches traces, matches on (operationName, serviceName, parentOperation), and reports duration/tag deltas, providing transparency beyond 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?

Well-structured with examples and a returns section; front-loaded purpose. Every sentence is useful, 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?

Given tool complexity, output schema existence, and rich annotations, the description fully covers matching logic, use cases, and return structure, leaving no gaps.

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% with descriptions for both parameters. The description adds value by mentioning 'Obtain from jaeger_search_traces' and context on hex format, slightly improving over the baseline 3.

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 'Compare two traces structurally — find added, removed, and changed spans.' It uses specific verbs and resources, and distinguishes from sibling tools by explicitly contrasting with aggregate statistics and single-trace inspection.

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?

Provides explicit when-to-use examples (e.g., 'What changed between a fast and slow request?') and when-not-to-use with alternatives (e.g., 'use jaeger_get_trace'), giving clear context for tool selection.

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, destructiveHint=false. The description adds context about fetching traces, aggregating per operation, and comparing, without contradiction.

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?

Well-structured: purpose sentence, what it does, bullet-pointed usage scenarios, and exclusions. Front-loaded and concise.

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 7 params (5 required), 100% schema coverage, output schema present, and rich annotations, the description covers all necessary context without gaps.

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. The description adds meaning through usage examples that implicitly reference parameters (e.g., pre/post-deploy windows), though it doesn't describe each parameter explicitly.

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: compare aggregate trace behavior between two time periods for a service. It uses specific verbs and distinguishes from siblings like jaeger_compare_traces and jaeger_get_trace.

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?

Explicitly provides when to use (e.g., deployment impact, database upgrade) and when not to use (specific trace comparison, full span detail), with alternative sibling tools mentioned.

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, destructiveHint=false. The description adds valuable context: it finds the longest-duration span chain, ranks spans by self-time, and returns a dict with trace metadata, critical path spans, and bottleneck ranking. No contradictions.

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, front-loaded with the purpose, and structured with bullet points for usage examples, non-usage cases, and return value. Every sentence adds 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?

Given the tool's moderate complexity, single parameter, existing output schema, and thorough annotations, the description is complete enough for an agent to understand when and how to use it.

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% for the single trace_id parameter, which is well-described in the schema. The tool description adds no extra parameter information beyond what the schema provides, so 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 identifies the critical path and top bottlenecks in a trace. It distinguishes from siblings by explicitly noting when not to use (e.g., for aggregate statistics or comparing traces) and naming alternative 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?

Multiple 'Use when' examples are provided, each with a clear scenario and expected action. 'Don't use when' cases specify alternative sibling tools (jaeger_span_statistics, jaeger_compare_traces), offering explicit 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 indicate readOnlyHint=true and idempotentHint=true. The description adds how it fetches traces and computes statistics, which is useful context. No contradictions or missing disclosures.

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?

Concise with clear sections: purpose, process, examples with usage, returns. No wasted words; front-loaded with key information.

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?

Covers all necessary aspects: purpose, parameters, examples, alternatives, return type. No unexplained gaps given the tool's complexity and existing annotations.

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 baseline is 3. The description adds value by providing concrete examples of using parameters (e.g., sensitivity, duration windows) beyond the schema definitions.

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 it detects latency and error-rate anomalies for a service by comparing recent behavior to historical baseline. It uses specific verb 'detect' and resource 'anomalies for a service', and distinguishes from siblings like jaeger_compare_windows and jaeger_get_trace.

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?

Provides explicit 'Use when' examples with parameter suggestions and 'Don't use when' with alternative tool names, giving clear guidance on when to use this tool versus others.

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?

The description adds valuable behavioral context beyond the annotations: 'Accepts any tag key-value schema without normalization' indicates flexibility and a lack of preprocessing, while 'searches all known services concurrently (capped at 20)' and 'sorted newest-first' disclose performance and ordering traits. These enrich the annotation-provided readOnly and idempotent hints without contradiction.

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, front-loaded with the main action, and uses three clear sentences. Every sentence earns its place: purpose, tag flexibility, and key behaviors.

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 schema, annotations, and presence of an output schema, the description covers the essential behavioral aspects. It lacks explicit differentiation from the similarly named 'jaeger_search_traces', which could cause selection ambiguity, but is otherwise 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 coverage is 100%, so the baseline is 3. The description adds some context (e.g., tag schema flexibility, service omission behavior) but does not significantly deepen understanding of individual parameters beyond the schema. It is adequate, not outstanding.

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 'Find Jaeger traces matching the supplied tag query', which is a specific verb+resource. However, it does not explicitly distinguish itself from the sibling tool 'jaeger_search_traces', which may serve a similar purpose.

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 clear context on when to use it (tag-based query, any tag schema) and notes that service is optional with a fallback to all services. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to infer use cases.

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?

The description adds behavioral details (confidence intervals, 7-30 day range) beyond annotations, but contains an inconsistency: it states 'next 7-30 days' while the schema allows days_ahead from 1-90. This misstatement reduces transparency.

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 with two clear paragraphs: purpose and parameters. It is front-loaded and well-structured, though the range inconsistency could be clarified.

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 presence of an output schema and annotations, the description provides adequate context (throughput, resource requirements, confidence intervals). The inconsistency in the forecast range is a minor 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 coverage is 100%, so baseline is 3. The description repeats schema info (service name, default days_ahead) but adds no new semantic value beyond what the schema already provides. The mention of 7-30 days could mislead regarding the valid range.

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: forecasting future throughput and resource requirements for a service. It uses specific verbs (forecast) and nouns (capacity for a service), and distinguishes it from sibling tools like prediction and anomaly detection.

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 infrastructure scaling decisions, providing context. However, it does not explicitly state when not to use or direct users to alternative tools like jaeger_predict_degradation for degradation-specific predictions.

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 provide readOnlyHint and idempotentHint; the description adds that the dependency graph is aggregated and may lag by minutes, and that it wraps GET /api/dependencies. It also discloses the return structure including fields like end_ts_us, lookback_hours, edge_count, and edges.

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 well-structured: brief intro, clear bullet points for use cases, explicit don't-use cases, and a return format summary. Every sentence adds value without redundancy.

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 low complexity (2 parameters, all optional), the description covers all necessary aspects: purpose, usage guidelines, behavioral caveats, and return format. It is fully adequate for an agent to select and invoke the 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?

Schema description coverage is 100% with both parameters well-documented. The description adds value by providing concrete examples of parameter usage (e.g., lookback_hours=168 for 7 days), but the schema alone already explains the parameters adequately, so this is slightly above baseline.

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 'Retrieve' and specific resource 'service-to-service call graph from Jaeger'. It distinguishes from sibling tools by providing explicit use cases and when not to use it, e.g., 'Don't use when: You want detailed span timings (use jaeger_search_traces + jaeger_get_trace instead)'.

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 explicit guidance on when to use this tool with concrete examples (e.g., 'What services does order-service call?', 'Map the full service dependency graph for the last 7 days'), and when not to use it with alternatives, such as for real-time data or detailed span timings.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true, so behavior is well-covered. The description adds useful context like error span identification ('tags["error"] = "true"'), return structure details (services, execution_tree), and API endpoint mapping. 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?

The description is well-structured with clear sections: purpose, API endpoint, return details, examples, and don't-use guidance. Every sentence adds value, and there is no redundancy. The examples are concise yet informative.

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 single-parameter tool with rich annotations and an output schema described in the description (listing all return fields), the description is complete. It covers all necessary information for an agent to correctly invoke and interpret results.

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% with detailed constraints (pattern, minLength, maxLength, description). The description repeats the format and examples but does not add significant meaning beyond the schema. 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 'Retrieve full trace detail with all spans, service breakdown, and execution tree.' The verb 'Retrieve' and resource 'full trace detail' are specific. It effectively distinguishes from sibling tools like jaeger_search_traces (which finds traces) and others by explicitly contrasting use cases.

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?

Explicit examples of when to use (e.g., 'Why is trace abc123... slow') and when not to use (e.g., 'Don't use when: You don't have a specific traceID — use jaeger_search_traces to find one first') are provided. Alternatives are named clearly, and the examples demonstrate suitable scenarios.

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?

Beyond annotations (readOnly, idempotent), the description adds that output is capped at 500 operations and details the return dict structure. 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?

Efficiently structured: summary, API wrap, usage guidance, examples, return format. No superfluous text; every sentence adds 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?

Given single parameter and simple operation, description fully explains purpose, usage, constraints (500 cap), output structure, and relationship to 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?

The single parameter 'service' is described in schema with 100% coverage. Description adds context that the name must match exactly as returned by jaeger_list_services, adding value beyond 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 'List' and resource 'operation names' for a given service. It distinguishes from siblings like jaeger_list_services and jaeger_search_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?

Provides explicit when-to-use examples (discovering operation names for filtering) and when-not-to-use (when service unknown or name already known), with alternatives suggested (jaeger_list_services).

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, but the description adds context beyond that: no pagination, output capped at 500 services with truncation hint, and wraps a GET endpoint. 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?

The description is well-structured with a clear opening, a technical note, sections for examples and returns. Every sentence is informative, and it is front-loaded with the main purpose.

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 simplicity (no parameters, output schema provided), the description covers all necessary aspects: behavior, usage, limitations, and return format. It is complete and self-contained.

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 no parameters, and schema description coverage is 100%, so baseline is 3. However, the description adds value by explicitly stating there are no parameters needed and how to call it, making it more helpful than the baseline.

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 lists all services observed by Jaeger, using a specific verb and resource. It distinguishes itself from sibling tools by explaining when to use it and when not to, such as referencing jaeger_list_operations and jaeger_search_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?

Explicit usage guidelines are provided, including when to use (e.g., discovering service names, checking if a service is instrumented) and when not to use (e.g., when service name is known or need dependency graph). It also names alternatives like jaeger_search_traces.

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, providing a safe profile. The description adds value by detailing the analysis approach (historical trace data, critical path trends, anomaly detection) and the prediction horizon (2-24 hours), which goes beyond the annotations and clarifies behavioral traits.

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 with a clear structure: purpose sentence, analysis approach, parameter list, and return overview. Every sentence earns its place, and critical information 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?

Given the tool's simplicity (2 parameters, no nested objects) and the presence of an output schema, the description is complete. It explains the purpose, input parameters, and return value (degradation forecast, confidence, recommendations), fitting the context well.

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%, with both 'service' and 'hours_back' having descriptions and constraints. The description repeats these but adds no new semantics beyond the schema. Baseline 3 is appropriate as 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 predicts potential performance degradation events for a service, using historical trace data. The verb 'predict' and resource 'degradation' are specific, and the content distinguishes it from siblings like jaeger_detect_anomalies or jaeger_forecast_capacity by focusing on forecasting issues 2-24 hours in advance.

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 predicting degradation but does not explicitly state when to use this tool versus alternatives like anomaly detection or capacity forecasting. No exclusions or when-not-to-use scenarios are mentioned, leaving the agent to infer context from sibling names.

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 mark the tool as readOnly, idempotent, and non-destructive. The description adds behavioral context by explaining that it fetches traces from both windows, classifies operations into four categories, and sorts results by severity score. This goes beyond the annotation hints and helps the agent understand the processing flow and output ordering.

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, consisting of three sentences with no filler. The first sentence is a clear front-loaded summary; the following sentences add relevant detail about the classification categories and severity sorting. Every sentence contributes to understanding the tool's 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?

The description is complete for a read-only analysis tool with a rich schema and an output schema available. It explains the core process (fetch, classify, sort) and the classification labels, which covers the main behavior. Some could argue it doesn't mention default window behaviors, but those are already documented in the schema, and the output schema explains return values, so the description is sufficiently 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 covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds minimal parameter-specific meaning beyond the schema; it implies the time parameters pertain to baseline and comparison windows but does not elaborate on syntax or interactions. The schema already provides sufficient semantic detail for each parameter.

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 function: comparing two Jaeger time windows and classifying per-operation regressions. It enumerates specific classification outcomes (regressed, recovered, appeared, removed) and mentions sorting by severity score, distinguishing it from siblings like jaeger_compare_windows which may only compare windows without classification.

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 implicitly conveys when to use the tool: when you need to compare two time windows to identify regressions and related operation changes. However, it does not explicitly mention alternative tools or provide exclusions (e.g., when to use jaeger_compare_windows instead). The context is clear but lacks explicit guidance on tool selection.

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 indicate read-only, idempotent behavior. The description adds that it wraps a GET API, returns trace summaries, details on parameter formats (JSON tags, duration strings), and mentions truncation. Does not conflict 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?

Well-structured with intro, parameter details, examples, and usage notes. Slightly verbose but every sentence adds value; could be more concise.

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 complexity (8 parameters, high schema coverage, good annotations, and output schema hinted), the description is comprehensive. It covers usage, parameter formats, examples, and limits, leaving minimal gaps.

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?

Since schema_description_coverage is 100%, the baseline is 3. The description adds value by explaining how tags and durations are interpreted, and provides concrete examples mapping user intents to parameter values.

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 it searches Jaeger traces with rich filters, uses a specific verb, and distinguishes from sibling tools like jaeger_get_trace and jaeger_get_dependencies.

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?

Explicitly provides when-to-use examples (e.g., recent errors, slow traces) and when-not-to-use conditions (if you already have a trace ID or need dependency topology), along with naming alternatives.

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 agent knows this is a safe read. The description adds rich behavioral context: it aggregates spans by operation name, reports p50/p95/p99 in microseconds, error rate formula, and the return structure. No contradictions 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?

The description is well-organized: a one-sentence summary, then calculation details, units, examples, exclusions, and return value. Every section earns its place—no wasted words, and the 'Returns' block clarifies expected output even though an output schema exists.

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 (aggregation, multiple metrics, parameter combinations) and the presence of an output schema and annotations, the description is thorough. It covers use cases, parameter effects, output format, and explicitly lists sibling tools for alternatives, leaving little ambiguity for the agent.

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% with each parameter described, so the baseline is 3. The description adds value by explaining how 'limit' affects sample size/accuracy and that 'operation' filters traces before aggregation. It also gives parameter-specific examples (e.g., service='order-service'), but it doesn't fully replace the schema's role.

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+resource+scope: 'Compute per-operation latency percentiles and error rates across recent traces.' It clearly distinguishes from siblings by stating 'Don't use when: You want to compare two specific traces (use jaeger_compare_traces instead)' and similarly for jaeger_get_trace.

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?

Explicit 'Use when' and 'Don't use when' sections provide concrete example queries with parameter settings and alternative tool names. This gives the agent clear decision rules for when to select this tool versus siblings like jaeger_compare_traces and jaeger_get_trace.

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/idempotent/non-destructive, and the description adds useful behavioral context by stating operations are ranked by descending total wall time. This goes beyond what annotations provide and does not contradict 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?

Two sentences with the main action in the first and ranking behavior in the second—no filler or redundancy. The description is front-loaded and efficient.

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 aggregation tool with a full schema and an output schema, the description provides the core behavior and ranking detail. It is complete enough, though it could benefit from clarifying when to prefer this over sibling analysis tools, which is already penalized in other dimensions.

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 descriptions cover 100% of parameters with clear explanations (tags, limit, service, lookback_hours), so the description needn't add details. It only references 'tag query' which aligns with the tags parameter, adding no extra 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 tool aggregates per-operation latency hotspots across traces matching a tag query, using specific terminology ('per-operation', 'latency hotspots', 'ranked by total wall time') that distinguishes it from siblings like jaeger_search_traces or jaeger_span_statistics.

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 provided on when to use this tool versus the 14 sibling tools. It does not mention alternatives or exclusions, leaving the agent to infer usage from the name and description.

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