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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds one useful behavioral fact ('Results are bounded'), but omits the actual limits (limit default 100/max 500, rangeSec default) that matter for a discovery call.

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, both front-loaded and free of filler. The scope-narrowing hint is placed after the core purpose, which is appropriate ordering.

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 6-parameter, zero-coverage tool with no output schema, the description is too thin. It never explains time-range defaults, the limit cap, or what the returned hit counts represent, leaving the agent to guess at invocation semantics.

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 0% across 6 parameters, so the description carries the full burden, yet it only names query/filter and alludes to bounded results. start, end, limit, and rangeSec are left completely unexplained by both schema and description.

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 ('Discover available log field names and hit counts'), which clearly differs from siblings like field_values (which returns values). It stops short of naming the sibling it is not, so an agent must infer the boundary from names alone.

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 query/filter to narrow scope' gives a concrete narrowing hint, but there is no explicit when-to-use versus alternatives such as field_values or hits, and no exclusions. Usage is implied rather than guided.

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 supply the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description need not restate it. It adds the useful constraint that the field is required and the window must be bounded, but says nothing about the limit cap, default range behavior, or result ordering/pagination.

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 no filler. It is efficient, though its brevity borders on under-specification for a seven-parameter tool rather than true economy.

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 tool with 0% schema description coverage, no output schema, and no help text on query/filter semantics or defaults, one sentence is not enough. An agent knows what the tool returns but not how to shape the request.

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 0% across 7 parameters, so the description must compensate — yet it only alludes to 'field' and the time window. The query/filter pair, the '*' default, and the 100/500 limit bounds are documented nowhere, leaving most parameters unexplained.

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 ('Discover') and resource ('values and hit counts for a required field'), which cleanly separates it from the sibling field_names tool that only lists names. It is clear what the tool returns, though it never explicitly names the alternative tools it competes with.

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 or when-not-to-use guidance. 'Bounded time window' hints that a time constraint is mandatory, but the description never says when to pick field_values over search_logs, hits, or query_stats, despite seven sibling tools that overlap.

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

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

Annotations already cover read-only/idempotent/safe, and the description adds real behavioral context: the default 60s step, the max 10000 bucket cap, the default one-hour window, groupsLimit default 20 with max 100, and the overflow-group behavior. It stops short of describing auth needs or the exact response shape.

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 dense sentences, front-loaded with the core purpose and limits, with no filler. It is information-packed but readable; a slight risk of overload from stacking bucket limits and group limits in one sentence.

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 partially compensates by explaining bucket counts, top groups, and the overflow group. Still, for an 8-parameter aggregation tool with 0% schema coverage and no output schema, the query/filter syntax and time-range parameters are meaningfully under-explained.

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 0% across 8 parameters, so the description must carry the load. It explains stepSec, groupsLimit, fields-based grouping, and the default window, but start, end, query, and filter (the actual log-selection inputs) are undocumented in both schema and description.

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 ('Count logs over time') plus the bucketing mechanism, which is clearly distinct from raw-log search. However, it never names or contrasts with siblings like search_logs or query_stats, so an agent must infer the distinction from the aggregation semantics alone.

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 describes what the tool produces but gives no explicit when-to-use guidance, no conditions under which to prefer this over search_logs or query_stats, and no note about prerequisites. Usage is only inferable from 'count ... over time'.

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 disclose read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond annotations: the output values are stream IDs consumed by search_stream, and a limited subset may have zeroed hit counts.

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

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

The description is short and front-loaded, moving from purpose to output/usage to caveat. Every sentence adds relevant information without repetition or filler.

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

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

The description covers purpose, output identity, and a hit-count caveat, and annotations cover the safety profile. However, with no output schema and 0% parameter description coverage, it omits any explanation of the six input parameters, leaving a clear completeness 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 0% and the description says nothing about the six input parameters (limit, query, start, end, rangeSec, filter). With low coverage, the description needed to compensate but does not, leaving parameter meaning entirely undocumented.

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

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

The description uses a specific verb ('Discover') and resource ('stream IDs and hits') and clarifies the returned values are _stream_id strings usable by search_stream. This distinguishes it from the sibling search_stream tool without requiring the agent to open either schema.

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 clearly implies the discovery-then-search workflow by saying the values are usable by search_stream. There is no explicit when-not guidance or mention of other alternatives such as field_names or search_logs, but the context is clear enough for an agent to route correctly.

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 readOnly/idempotent/non-destructive, so the description adds real behavioral value beyond them: it returns 'original JSON rows without log normalization', names the backing endpoint, and discloses the default window (last hour) and row cap (max 500). It doesn't cover pagination interaction with offset or truncation signaling, which would push this higher.

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?

Four short sentences, front-loaded with the core purpose and an inline example. Each sentence carries distinct information (purpose, return shape, endpoint, defaults), though the endpoint/API clarification is the least essential for invocation.

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 context, and it does so briefly ('original JSON rows without log normalization'). Combined with the stated defaults and row cap it is reasonably complete, but the seven undocumented parameters and the missing behavior for offset-based pagination leave meaningful gaps for an aggregation 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 coverage is 0% across 7 parameters, so the description must compensate, and it only partially does: it confirms the 500-row limit and the one-hour default, matching the schema's limit and rangeSec defaults. It says nothing about start/end formats, offset semantics, or the relationship between the query and filter properties, leaving most parameters undocumented.

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: 'Execute a LogsQL aggregation pipeline' with a concrete example ('* | stats by (service) count() as errors'). It also clarifies the execution path ('/select/logsql/query, not the Prometheus stats API'), which separates it from an adjacent-but-different API, though it does not name a sibling tool like search_logs or hits directly.

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 aggregation framing implies this is for stats/summary queries rather than raw log retrieval, and the Prometheus-API note clarifies a boundary. However, it never states when to prefer this over search_logs, search_stream, or hits, nor any prerequisites for the LogsQL pipeline. Usage is implied rather than explicit.

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 real behavioral context beyond that: default window of last hour, 150 rows with a 500 cap, end-exclusive time bounds, and the stability requirement for paging. It stops short of describing result shape or error 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?

Dense and front-loaded: query language first, then defaults, then time-window options, then filtering and pagination. Every clause carries information, though the middle-clause run-on is slightly compressed for readability.

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 should sketch what search results look like (row/log shape, ordering), but it never does. Parameter and pagination behavior are well covered, so the definition is adequate but leaves the return contract implicit.

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 0%, so the description carries the burden and largely does: it explains rangeSec vs paired ISO start/end (end exclusive), that filter is a separate LogsQL extra_filters constraint distinct from query, and how limit/offset behave. Only minor gaps remain (e.g., no explicit statement of units beyond default 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?

States a specific verb ('Search') and resource ('VictoriaLogs') plus the query language ('LogsQL'), so the operation is unambiguous. It does not, however, differentiate itself from close siblings such as search_stream or search_uuid.

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 practical operating guidance for pagination ('offset paginates the selected window; keep start/end fixed across pages'), which implies the intended usage pattern. It never states when to prefer this tool over siblings like search_stream, hits, or query_stats, so alternative selection is left to inference.

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, so the safety profile is covered. The description adds the default time window, but that value is already the rangeSec schema default (3600), and it says nothing about pagination or the 500 limit cap. Adds marginal 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 core operation and followed by the discovery hint and default window. No filler; every sentence carries actionable 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 6-parameter, no-output-schema tool this is thin: four of six parameters are unexplained and there is no note on what a result contains or how limit interacts with the time window. The required parameter and its discovery path are covered, which keeps it at minimum-viable rather than inadequate.

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 0% across 6 parameters, so the description carries the full burden and largely fails. It restates the streamId pattern (already encoded in the schema) but never explains filter syntax, limit behavior, or the start/end vs rangeSec relationship.

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 ('Search a VictoriaLogs stream') plus the key identifying field (48-character hex _stream_id), which is enough to separate it from the other search siblings. It stops short of explicitly contrasting with search_logs/search_uuid, so an agent still has to infer which search family applies.

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 real routing guidance: it names list_streams as the way to discover IDs and states the default time window. It lacks an explicit 'when not to use' (e.g. use search_logs when you don't have a stream ID), but the discovery pointer handles the main selection decision.

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, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: the default time window (last day) and the search scope (exact-value fields + _msg phrase). It says nothing about result volume, the limit parameter, or pagination, so it stays at a moderate 3.

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 with no filler; the search target is front-loaded ahead of the window detail. Efficient, though for a 6-parameter tool the extreme brevity borders on under-specification rather than pure conciseness.

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 6-parameter search tool with no output schema and 0% schema description coverage, the description is too thin: filtering, limits, and time-range parameters are undocumented and nothing is said about what a hit looks like. It does not carry the full burden left by the structured fields.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and largely does not. It hints at the uuid input and the rangeSec default ("last day") but leaves limit, filter, start, and end entirely unexplained in both schema and text.

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?

Names a specific verb ("Find") and a concrete resource set (UUID, trace, request, correlation ID) and explains the search surface: exact-value fields plus a phrase in _msg. An agent can tell it apart from generic siblings like search_logs, though the description never names those 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?

Usage is implied by the resource type (searching for an identifier) and the default window is stated, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as search_logs or search_stream. The agent must infer that this tool is for identifier lookups vs. free-text queries.

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