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

With no annotations provided, the description carries the full behavioral burden and discharges it: it discloses the sampling strategy (stratified across `kubernetes.container_name` via FIELDS_STRATIFY_FIELD so rare container types contribute), the extraction method (walks each doc's `_source`), deduplication, and result grouping that collapses `kubernetes.annotations.*`. It also notes enrichment from the field-caps API when available. These details materially affect how the agent should interpret the returned field list.

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 purpose is front-loaded in the first sentence, followed by usage guidance and a closing tip; every paragraph carries information. The one redundancy is restating the 'call once / rarely re-call' point in two separate sentences, which costs a little tightness.

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 10-parameter, no-output-schema tool, the description covers the essentials: what is returned (deduplicated, type-annotated, aggregatability-annotated field paths), how it is shaped (grouped/collapsed), and when to invoke it. It does not describe response envelope details or any bound on the sampled document count, which is a minor gap given there is no output schema to fall back on.

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 70% and the schema already documents each parameter in detail (level, query, query_dsl, include/exclude_filters, time windows). The description only gestures at parameter behavior ('found in a sample of matching log docs', the stratify env var) without adding syntax or semantics beyond what the schema states, 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 gives a precise verb and resource: 'Returns every populated field path (dotted) found in a sample of matching log docs,' plus the schema-discovery intent ('learn the schema: what `aggregate_fields` and `display_fields` paths are valid'). This is unmistakably distinct from the sibling search/inspect/summarize tools, which operate on log content rather than on the field inventory.

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 states when to call it ('Call this ONCE at the start of a fresh investigation'), when not to ('Subsequent investigation turns rarely need to re-call this because the schema is stable across queries'), and how to pair it ('pair it on the very first turn with a `summarize_logs` call (in parallel)'). This is a textbook when/when-not/alternative instruction.

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?

No annotations, so the description carries the full burden. It discloses the default window (±60s total 120s), the scoping default (all traffic unless filtered), and a real pitfall (putting ERROR in query also matches INFO messages containing the word). It does not state read-only status or the query cost of a wide window, leaving a small gap.

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?

Front-loaded with purpose, then progressively refines tuning and scoping advice. Four short paragraphs, each earning its place, though the default-window value is stated twice (once in prose, once implicitly via window_seconds) and the parenthetical about the 120s total is slightly redundant.

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, nested-object tool with no output schema, the description covers the operationally critical parameters (timestamp, window_seconds, trace_id, include_filters, query, level) well. It leaves full_message and display_fields (answered only by a cross-reference to search_logs) largely unexplained, which is a modest gap given the high schema 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 83%, so the baseline is 3. The description adds genuine semantics beyond the schema: window_seconds is a half-window (±60s), trace_id overrides a configurable field, query should usually be empty, and include_filters is 'highly recommended' to avoid drowning in unrelated traffic.

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 (returns) and resource (log entries in a time window around a timestamp), and the Kibana 'view surrounding documents' analogy pins down the exact behavior. The framing 'when you've found a suspicious entry... see what happened immediately before and after' distinguishes it from sibling search_logs (broad search) and inspect_log (single-entry detail).

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 about when to use it, how to tune the window (narrow for noisy services, widen for sparse logs), how to scope via trace_id or include_filters, and the consequence of not scoping ('you'll see ALL traffic in the window, which is often too much'). It even advises when to leave query empty.

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?

With no annotations, the description carries the full burden and does so well: it enumerates exactly what default trimming destroys (raw `log` dropped, stack traces cut to 5 frames, annotations collapsed, strings over 4000 chars cut), how to opt out with `full: true`, that only the first match is returned, and that the extension has no configured environments. This is unusually rich behavioral disclosure.

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 paragraphs, front-loaded with purpose then behavior then identification strategy; every sentence earns its place. The trimming details are somewhat restated between the body and the `full` parameter description, a minor 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?

No output schema and no annotations exist, yet the description specifies the return format (YAML `_source`), the default trimming behavior, the escape hatch, and the match-selection semantics. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why `timestamp` is the primary key and when it is insufficient, and frames `include_filters` as a disambiguation mechanism rather than a generic filter. It does not add syntax beyond the schema, keeping it below 5.

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 `_source` of one log entry as YAML') and immediately contrasts it with search by framing the trigger as 'when search shows a tantalizing single message and you need the full metadata.' An agent can distinguish this from search_logs and get_log_context without opening a 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?

Gives a clear when-to-use condition (after a search surfaces one interesting message) and explains the disambiguation path when the timestamp is not unique. It never explicitly names a sibling tool or states when-not-to-use, so it stops short of a 5.

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

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

With no annotations the description carries the full burden, and it does disclose key non-obvious traits: dependency on a Chrome extension bridge, the correct failure behavior (report the error rather than improvising browser automation), the fallback-chain rendering behavior, and that no environments are currently configured so 'environment' should be omitted. It stops short of disclosing rate limits, latency, or result-shape details, keeping it below a 5.

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?

Front-loads purpose, then numbers the workflow, then flags the browser-automation caveat in caps — good information architecture for a 14-parameter tool. It runs long and duplicates some schema content (e.g. the available_log_fields / display_fields guidance appears in both the workflow and the parameter descriptions).

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 complex, 14-parameter tool with no output schema, the description supplies workflow, dependency, failure handling, and rendering behavior. It omits what a returned hit looks like and roughly how expensive a search is, but nothing critical to calling it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds cross-parameter semantics the schema can't: the exclude_filters narrowing loop, the display_fields fallback rationale tied to empty renders, and the level-vs-query trade-off. Concrete example filter pairs are given, though several parameter details are still restated rather than extended.

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 verb+resource+transport ('Searches logs in Kibana / OpenSearch Dashboards via the active browser tab and returns hits'). It also implicitly demarcates itself from siblings by defining search_logs as the narrowing step after summarize_logs, so an agent can distinguish the two without opening 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?

Provides an explicit 5-step investigative workflow that names alternatives and the condition that selects each: start with summarize_logs for counts, use available_log_fields when messages render empty, pin a row with timestamp_match. It also states a when-not (do not attempt browser automation on failure) — unusually complete routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key behavioral traits: size=0 means no hits are returned, cost is cheap on tokens even over 7-day windows, defaults for aggregates, and that the response header shows the resolved UTC window. It does not cover permissions or rate limits, but the cost/shape disclosure is genuinely useful.

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?

Front-loaded with the return shape, then the routing rule, then a concrete example call. The second paragraph largely restates the first ('typical first call' repeats 'use before search_logs'), which is mild redundancy but keeps the guidance actionable.

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, nested-object tool with no output schema, the description states what is returned (hits total, histogram, top-N) and the cost profile, and defers field discovery to available_log_fields. It is complete enough to call correctly, though it does not warn about the interplay between time_from/minutes_lookback beyond what the schema states.

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 83%, so the schema already documents most parameters in detail. The description adds workflow meaning (exclude_filters should carry prior excludes so the summary reflects the narrowed set) but no syntax or format detail beyond what the schema provides; 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 first sentence states a specific verb (Returns), resource (a log query summary) and the exact payload (total hits, time histogram, top-N dimension values). It is immediately distinguishable from search_logs, which returns actual hits.

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 routes the agent: 'Use this BEFORE `search_logs` to see the shape of the data and decide which `exclude_filters` to apply,' and repeats the workflow in the typical-first-call example. Both the when and the alternative are named.

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