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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds real value by disclosing that results are normalised per hour, bucketed into new/increased/gone/decreased groups, and filtered to errors by default.

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?

Three tight sentences that front-load the core operation, then the split_at variant, then the output categories and default filter. No filler, though the parenthetical could be slightly cleaner.

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 12-parameter, no-output-schema tool, the description covers the default time basis, the split_at alternative, the grouping output, normalisation, and the errors-only default. It leaves period-length details to the schema, which is reasonable given 100% coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 12 parameters including split_at, window, and errors_only. The description restates the default window comparison and split_at semantics, which reinforces but does not meaningfully extend 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?

States a specific verb (compare) and resource (two periods of grouped log data), and clarifies the default comparison basis and the split_at variant. It does not name the closest sibling (detect_changes or error_summary), so an agent must still infer when to prefer this over those.

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 explains the default behavior (last window vs the one before, or around split_at) and the errors-only default, which implies typical usage, but it never says when to choose this tool over detect_changes, error_summary, or log_histogram.

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 structurally. The description adds nothing beyond that: no note on how the window is measured, what happens at log boundaries, result ordering, or the effect of the scope/query narrowing. For an open-world tool it under-discloses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with zero filler and the core scoping concept ('±N seconds') front-loaded. Its brevity is arguably under-specification rather than good economy, but there is no wasted text to trim.

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 six parameters, no output schema and an open-world read tool, the description leaves the agent without any guidance on how scope/query/instance interact or how to narrow the window sensibly. The schema covers individual params, but the description contributes no operational context for a moderately complex retrieval 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 scope, query, limit, instance and seconds are already documented in the schema, and the baseline is 3. The description's '±N seconds' does add the useful symmetry detail (seconds applies both before and after the anchor), but nothing else is elaborated 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 fragment 'Messages logged within ±N seconds of a given message' does convey a specific resource and a temporal-scope operation, so an agent can infer it fetches messages near an anchor. However, it is a bare noun phrase with no verb and no differentiation from siblings like get_message or search_logs, which also retrieve messages. Purpose is identifiable but not sharp.

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?

There is no when-to-use guidance at all — nothing says this is for pulling surrounding traffic around a known message versus using get_message for one message or search_logs for a query. The '±N seconds' framing only weakly implies a 'when you need surrounding context' scenario. No alternatives or exclusions 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=false, so the safety profile is covered. The description's only added behavioral claim is 'Cheap', which is a genuine cost signal not present in the structured fields, but it says nothing about count caps, accuracy limits, or whether the count is bounded.

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 zero filler, and the returned value is front-loaded ahead of the cost hint. Every clause carries 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?

For a parameter-rich but conceptually simple read tool with a full-coverage schema, a complete annotation safety profile and a stated return value, the description is adequate. It omits only what to do with the count or how it compares to the histogram, which 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 description coverage is 100% across all six parameters, so query syntax, range formats, streams, instance and the from_time-overrides-range rule are all documented in the schema. The description adds no parameter detail, 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?

States a specific verb and resource: returns the exact number of messages matching a query. The word 'Exact' usefully contrasts with the histogram sibling, but no sibling is named, so an agent still has to infer the boundary with log_histogram or search_logs.

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?

'use it to size a problem' implies a usage pattern (cheap pre-flight sizing before heavier queries) but gives no explicit when-not guidance and never names the alternatives (search_logs, log_histogram) that an agent should pick when it needs the messages themselves rather than a tally.

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, destructiveHint false, and openWorldHint, covering the safety profile. The description adds that detection is based on log patterns themselves (no CI/CD), which is useful behavioral context but does not cover return format or performance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the detection targets and the key differentiator (log-based, no CI/CD). Every phrase 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 read-only detection tool with full parameter documentation and no output schema, the description sufficiently explains what is detected and how. It could mention the shape of the output (e.g., list of change events), but the purpose and mechanism are clear.

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 six parameters are documented in the schema. The description adds no parameter-specific syntax or filtering guidance, leaving the baseline score.

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 detection task: finding deploys and restarts in logs via version field changes, host rollouts, and start/stop lines. It is clear what the tool does, though it does not explicitly differentiate itself from siblings like compare_periods or error_summary.

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 when-to-use guidance or alternatives are provided. The only contextual note is 'No CI/CD integration needed,' which is a feature, not usage guidance; an agent must infer that this tool is for log-based change detection.

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, non-destructive and openWorld, so the safety profile is covered. The description adds that it uses a preconfigured error query and returns exact counts plus first/last seen and a sample per group, but says nothing about limits on result size, cost, or timeouts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the operation and immediately states the grouping dimensions and the returned metrics. Every clause carries information; slightly long parenthetical nesting keeps it from being maximally crisp.

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 9 optional parameters, no output schema and read-only annotations, the description covers the purpose and the shape of results adequately, but omits routing guidance relative to the many sibling log-analysis tools. For a tool with this many knobs it is the minimum viable description.

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 including group_by, range, query and instance is already documented in the schema. The description only echoes the group_by options already listed there, so no meaning is added beyond the structured fields.

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 gives a specific verb (group) applied to a specific resource (errors) and enumerates the grouping dimensions and returned aggregates. An agent can tell it apart from most siblings, though it does not explicitly distinguish itself from the similarly grouping-oriented top_values.

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?

There is no explicit when-to-use guidance and no named alternative. It implies the tool always operates on a 'configured error query', which is useful context, but it never says when an agent should prefer this over count_logs, top_values or search_logs.

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, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that returned fields are redacted — but says nothing about pagination, error behavior, or what happens with an invalid ref.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with no filler, and the key retrieval scope and the redaction caveat are front-loaded. 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?

For a simple read tool with full schema coverage and clear annotations, the definition is nearly sufficient — it states the resource, the key, and that fields are redacted. With no output schema, a little more on the returned payload shape would help, but the gap is minor.

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 ref format, field filtering, instance selection, and stacktrace folding; the description's 'by ref' merely echoes the schema. Baseline 3 applies when structured data carries the parameter burden.

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-action (get) and resource (one message) plus the lookup key ('by ref'), so the agent knows exactly what it retrieves. It does not, however, distinguish itself from siblings like context_around or search_logs, which also surface message content.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as context_around for surrounding logs or search_logs for finding messages. The agent must infer usage purely from the name and ref semantics.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful content-level detail (that output includes configured trace fields and the error query), but says nothing about result size, truncation, or cost on large indices.

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, front-loaded with what is returned before the guidance sentence. No filler. The parenthetical and the clause about trace/error fields make it slightly denser than ideal, but nothing is wasteful.

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?

No output schema exists, so the description must carry return-value meaning; it does so by enumerating what the listing contains. For a simple read-only introspection tool with a fully documented schema and annotations, this is nearly complete, missing only result-size or pagination behavior.

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 three parameters (contains, instance, include_internal) are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline 3 case when structured data does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: listing field names and types. It also scopes the content to fields 'present in the indices' plus trace fields and the error query, which distinguishes it from siblings like list_instances or list_streams. It stops short of naming an alternative tool, so not a 5.

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?

Gives a clear usage condition: 'Use before writing queries on unfamiliar logs.' That tells the agent when this tool is the right first step. There is no explicit when-not or named alternative, so it lands at 4 rather than 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, fully covering the tool's behavior. The description adds only output content (version, API, redaction rules) and no behavioral context such as ordering, scope, or side effects. No behavioral traits beyond the annotations are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence with no wasted words and the resource is front-loaded. However, the fragmentary noun-phrase structure does not clearly state the action, which slightly reduces clarity.

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 no parameters and no output schema, the description usefully enumerates the fields returned by the listing. It stops short of explicitly saying the tool lists all configured instances, but the title and name fill that gap sufficiently for a simple read-only 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?

The tool takes no parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema is self-evident.

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 the specific resource (Graylog instances) but never states the action. It reads as an output summary rather than a purpose statement; the agent must infer 'list' from the tool name and title. The resource is distinct from siblings like list_streams, but the verb is missing.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The description only describes the returned data, leaving the agent to infer the tool's role entirely from the name.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only that presets originate in server configuration (i.e., they are static/predefined), with no return shape, auth needs, or refresh behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short fragment with no wasted words, but it is under-specified rather than concise — no leading verb and no statement of what is returned.

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 no parameters, no output schema and complete annotations, the description is minimally adequate, but it never states what listing yields (names only vs. full query definitions) and never links to run_preset, which is the main thing an agent would need to know.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter meaning is missing.

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 is a noun phrase, not a verb+resource statement; the listing action is only implied by the tool name. It does define what a preset is ('named queries defined in the server configuration'), which is slightly more than restating the title, but it gives no scope or differentiation from siblings like run_preset or list_fields.

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?

There is no when-to-use guidance, no mention of run_preset as the natural follow-up, and no exclusions. An agent must infer that this is a discovery step before executing a preset.

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, destructiveHint=false, and openWorldHint, covering the safety profile. The description adds one piece of behavioral context — that results are limited to what the token can read — but says nothing about return format or pagination, so it clears the lowered bar only modestly.

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?

Extremely short with no wasted words; the field list is front-loaded. The sentence-fragment style is terse to the point of under-specification, which keeps it just below a 5.

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 simple zero-required-parameter list tool with full schema coverage and annotations covering safety, the description is adequate but thin — it omits any mention of pagination or result limits and gives no usage routing, leaving gaps an agent must infer.

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 both parameters (instance, include_disabled) are already fully documented in the schema. The description adds no parameter-level detail, making the baseline 3 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?

States a clear verb and resource ('Streams ... the token can read') and enumerates the returned fields (id, title, description). It is specific enough to distinguish from most siblings, but does not explicitly contrast with list_instances, list_fields, or list_presets.

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 when-to-use guidance, no prerequisites, and names no alternatives. The only implicit context is the 'token can read' scoping, which hints at permissions but does not route the agent among sibling list tools.

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, non-destructive, openWorld, so the safety profile is covered. The description adds genuinely useful behavioral detail by naming exactly what is reported (peak bucket, first/last non-empty bucket, spike onset) and flagging 'exact' counting, which the annotations do not.

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 tight sentences, front-loaded with the core 'what', then the purpose clause. Little waste, though the parenthetical '(exact)' is slightly awkward placement.

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 annotations carry the safety profile and the schema fully documents all 7 params, the description's job is to convey output and intent, which it does. No output schema exists, but the description summarizes the returned figures, making it reasonably 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 every one of the 7 parameters is already documented in the schema. The description adds nothing parameter-specific beyond the 'exact' precision note, 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 verb and resource: 'Message counts over time (exact)'. Clear what it produces, but it does not distinguish itself from close siblings like count_logs or search_logs by name.

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?

'to find when a problem started' implies a usage context, which is better than nothing. However, it gives no explicit when-not guidance or named alternatives against siblings such as count_logs or compare_periods.

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 only declare the safety profile (readOnly, idempotent, non-destructive, openWorld); the description goes well beyond that by disclosing the comparison-against-baseline method, millisecond-level error pinning, deploy/restart/host-rollout detection, call-graph inference from traces, and the ranked-verdict-with-timeline output shape. That is substantive behavioral context an agent cannot get from structured fields.

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 core purpose is front-loaded in the first clause, the middle enumerates only capabilities that actually differentiate the tool, and the final short sentence gives the usage cue. No sentence is padding.

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 no output schema, the description must carry return-value semantics, and it does ('returns a ranked verdict with a timeline and evidence'). All 7 optional parameters are schema-documented, and the description supplies the analytical context an agent needs to call this correctly for incident triage.

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 for parameter understanding is already met by the schema itself. The description alludes to the baseline-comparison concept, which lightly reinforces the 'baseline' parameter, but adds no syntax, format, or defaulting 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?

Opens with a specific, high-signal statement of the job ('Find which service broke first and why') and then enumerates the concrete analytical steps it performs. An agent can distinguish it from error_summary, trace_request, and service_map because it explicitly fuses error, traffic, latency, deploy, and trace analysis into one ranked verdict.

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 closing line 'Start here for "what is causing this incident?"' gives a clear routing condition and makes this the default entry point for incident triage. It does not name sibling alternatives (e.g. error_summary or trace_request) or state when NOT to use it, so it falls short of full when/when-not 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=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, covering the safety profile. The description adds essentially no behavioral context beyond that – it says nothing about what a preset executes, whether it hits a remote instance, or what the result contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the core action first and the optional capability second; nothing is wasted. It is terse but not at the cost of clarity.

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 simple 3-parameter, non-destructive, read-only tool with full schema coverage and no output schema, the description is minimally adequate. It leaves the agent without context on what a preset is or what running one returns, but the safety profile is carried by 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%, with name, instance and overrides each documented in the schema itself (including the 'staging'/'prod' example and the override shape). The description's phrase "optionally overriding its arguments" adds no syntax or format detail beyond the schema, 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 states a specific verb and resource ("Run a named preset query") and notes the override capability, which is enough to distinguish it from the sibling list_presets. It stops short of explicitly naming alternatives such as search_logs, so it is clear but not fully differentiated.

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?

There is no explicit when-to-use or when-not-to-use guidance; the agent must infer that a preset must already exist (via list_presets) and that this is the execution step. No alternatives or preconditions are named, so usage is 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds useful behavior: results are 'compact, redacted lines' with a 'ref', and it discloses the default range of last 15 minutes, which is not in the schema. It doesn't mention rate limits or the dedup default, but this is solid context 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?

Three short sentences, front-loaded with the verb and query language, then output format, then default behavior. No filler and every clause carries 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 purpose, output shape, downstream usage, and default range for a read-only, idempotent search tool with a fully documented schema and no output schema. It does not explain pagination (offset/next_offset) or the default field set, but those are in the schema and the core call contract is clear.

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 11 parameters thoroughly. The description only adds the default range behavior and the 'ref' output concept; it doesn't explain query syntax or field filtering beyond what the schema provides. Baseline 3 is correct 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?

States a specific verb (Search) and resource (log messages) plus the query dialect (Lucene). The return type is described with concrete fields ('ref', index/id), giving it more precision than siblings like count_logs or log_histogram.

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?

Names the downstream tools that consume the 'ref' (get_message, context_around) and states the default range, which helps the agent know what this tool is for. It does not explicitly contrast with count_logs or log_histogram, so it's a clear context but not full alternative routing.

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, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: results are statistically inferred from sampling rather than from configuration, which tells the agent output is approximate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence that front-loads the core meaning ('which service calls which') and then enumerates outputs. No wasted words, nothing under- or over-specified.

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?

No output schema exists, but the description compensates by naming the returned content (edges with traffic, error rate, p50/p95 latency, entry points). Combined with full schema coverage and rich annotations, an agent has enough to call it correctly; only minor gaps like result size limits remain.

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 (query, range, sample, streams, time bounds, instance) is already documented in the schema. The description alludes to sampling but adds no syntax or format 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?

States a specific resource (service dependency map) and how it's derived ('inferred from sampled traces'), plus the output shape (edges with traffic, error rate, p50/p95 latency, entry points). It clearly reads as a topology/dependency tool, distinct from trace_request or root_cause, though it never names siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical '(no configuration)' implies the tool is the right choice when no instrumentation/config exists, which is useful implied context. However, there is no explicit when-to-use vs when-not guidance and no reference to alternatives such as trace_request or root_cause.

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 and openWorldHint=true, so the safety profile is fully covered. The description adds only that output includes exact counts and percentages, which is modest extra context and says nothing about aggregation cost, limits, or missing-field behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short, front-loaded sentence with zero padding. It is efficient, though arguably too sparse to count as optimally structured for an 8-parameter aggregation tool.

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 an aggregation tool with 8 parameters but no output schema, the description at least signals the shape of the result (counts and percentages). However it omits any guidance on limiting large result sets or on the query/range/time relationships, leaving the schema to carry the whole load.

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 all 8 parameters carry clear descriptions with examples, defaults, and bounds, so the schema does the heavy lifting. The description adds no syntax, interaction, or precedence detail (e.g. from_time overriding range) 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?

States a specific operation (top N values of a field) plus the return semantics (exact counts and percentages), so an agent can tell it apart from count_logs or log_histogram. It does not, however, name any sibling or scope the tool to a data source beyond the schema's implicit fields.

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 when-to-use or when-not-to-use guidance and no alternatives. It never hints at how this differs from count_logs, log_histogram, or list_fields, so the agent must infer selection from the name alone.

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 establish the safe/idempotent/read-only profile, and the description adds real behavioral context beyond that: the trace-field search with full-text fallback, and the shape of the result (chronological timeline, per-service steps with durations, first error). With no output schema present, disclosing the return structure is especially valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with a colon-delimited enumeration of the returned artifacts. Dense but every clause carries information; minor cost is that the enumeration makes it feel packed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, single-required-param tool with no output schema, the description covers core behavior and the return shape well. Gaps are modest: no pagination/truncation note, no statement on what happens when the trace id matches nothing, and no instance/time-range interaction guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 7 parameters are self-documented with defaults and formats. The description adds no parameter-level meaning (e.g. how limit interacts with the timeline, or that streams are optional), so 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 verb and resource: follows one request across services using trace fields, and specifies scope (all streams). It's clearly a trace-correlation tool rather than a generic log search, though it never names a sibling like search_logs or context_around to sharpen the contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: you need a correlation/trace id and want a cross-service timeline. There is no explicit when-to-use vs when-not guidance, no mention of alternatives (e.g. search_logs for free-text exploration), and no prerequisites or instance-selection advice.

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