Call first in every session to confirm connectivity and see the active backend.

Check the username field in the response to explain 403 errors on other tools — it shows exactly which role is authenticated. Returns backend ("dashboards" or "opensearch"), server version, URL, and username.

Requires cluster:monitor/health privilege — if you get 403, use opensearch_test instead.

Returns cluster status (green/yellow/red), node count, active shards, and unassigned shards. Useful to confirm the backend is not degraded before trusting query results.

If you get 403, use opensearch_list_index_patterns instead (lower privilege requirement).

Returns all indices sorted by name with doc count, store size, and health. Use this to find the exact index name before querying — date-sharded indices follow a pattern like wazuh-alerts-4.x-2026.06.24.

Dashboards-only alternative to opensearch_list_indices when _cat/indices access is blocked.

Returns id, title, and time field name for each index pattern as configured in the OpenSearch Dashboards UI. Requires the Dashboards backend to be active.

Use to see all field names and types; if you get 403 use opensearch_discover_fields instead.

opensearch_discover_fields only requires search privilege (not indices:admin/mappings/get) but only returns fields present in sampled documents. Returns nested fields flattened to dot-notation, e.g. "rule.level": "integer".

Fallback for opensearch_get_mapping when the mapping API is blocked; samples live documents.

Only returns fields that actually appear in the sampled documents — fields absent from the sample won't be listed. Unlike opensearch_get_mapping, only requires search privilege. Increase sample_size for broader field coverage (max 100).

Full-document retrieval using Lucene syntax (same as the Dashboards search bar).

Always pass source_fields to limit response size — 50 full docs ≈ 237 KB and will fill context quickly. Omitting from_ts/to_ts scans the full index history, which is slow and expensive; adding a time range reduces query time by up to 15×.

Fastest way to check how many documents match a condition; never returns content.

Prefer over opensearch_search when you only need the count — it never fills context with document data. Without from_ts/to_ts, scans the full index (4–5 s on 50 M docs).

Frequency table for a keyword field — top N values with their document counts.

If results look wrong or you see a heap warning, append .keyword to the field name (e.g. agent.name.keyword). Never use on analyzed text fields like rule.description — aggregations on text fields load fielddata into cluster heap.

Preferred over calling opensearch_terms in a loop — single round-trip for multiple fields.

Inherits the .keyword guidance from opensearch_terms: append .keyword to any text-like field name to avoid fielddata heap pressure.

Event count over time; always specify from_ts and to_ts (meaningless without a range).

Use interval="auto" when unsure — it picks ~50 buckets and is always safe. Fine intervals over long ranges (e.g. "1m" over a week) are rejected before the query runs to protect cluster resources.

Min/max/avg/std for a numeric field. Only works on numeric types (integer, float, long).

Passing a text field returns a 400 error with a clear message. Use opensearch_terms if you want frequency counts for a keyword field instead.

Execute a PPL (Piped Processing Language) query against OpenSearch.

Prefer over opensearch_search when you need multi-step pipeline operations (filter → stats → sort) in a single query. Not interchangeable with Lucene — different syntax. Returns 404 if the PPL plugin is not installed.

PPL syntax: source= | [| ...] Common commands: where — filter rows stats count() by — aggregate fields , — select columns sort - — order results (- = descending) head — limit rows

Escape hatch for any read GET endpoint not covered by other tools.

Use when you know the OpenSearch REST path but no dedicated tool exists. For search/count/terms/histogram use the dedicated tools — they add safety guards and better error messages. Only GET is supported; write/admin paths (_delete, _bulk, _update, _reindex, etc.) are blocked.

Explain why a specific document matches (or doesn't match) a query.

Use after opensearch_search returns unexpected results and you have a known document ID. Get the doc ID from a prior search by including "_id" in source_fields (note: _id is a metadata field — use opensearch_search and read the _id from hits). Exact index name only — no wildcards.

Get index settings: shard count, replicas, refresh interval, and ILM policy name.

Use to understand why an index behaves unexpectedly — e.g. slow writes from a short refresh interval, data loss risk from zero replicas, or unexpected retention from an ILM policy. Prefer opensearch_get_mapping for field schema exploration.

Compare the top values of a field between two time windows.

Prefer over calling opensearch_terms twice manually — computes the diff and percent change automatically. Use to detect new patterns, increased/decreased activity, or disappeared sources between a baseline and a selection period.