Log10x MCP

Resolve a raw log line or pattern name to its pattern hash, which is the same for the same line under the same engine, symbol library and configuration, then return byte volume + share per service (with cost overlay when $/GB is set), before→after delta, first-seen timestamp within the observation window, and the current offload disposition (pass / sample / compact / drop) read from the Reporter `routeState` label; only when `LOG10X_AI_SUMMARY=true`, an AI category for the pattern (error/debug/info/metric/health) with a one-line explanation. **Call this first** whenever a user pastes a SINGLE log line and asks "what is this", "is this new", "is this safe to drop", or "is this being dropped / offloaded". The lookup is structural, not byte-exact: different timestamps/request IDs/user IDs on the same underlying pattern resolve to the same hash. If no match is returned, say so. Use log10x_resolve_batch instead when the user pastes MULTIPLE events, a SIEM dump, or a batch to triage.

Pull recent live events for a pattern from the customer's log analyzer (Splunk, Datadog, Elasticsearch, CloudWatch) and return them grouped by templateHash with template-extracted slot values per match. **Bounded to a 24-hour window** (live log analyzer retention); for older history use `log10x_retriever_query`. Input is either a Symbol Message (pattern name like `Payment_Gateway_Timeout`) or a pasted raw log line; pasted lines resolve via the same templater path as `log10x_resolve_batch`. The tool runs a SIEM phrase-search probe, runs returned events through the local templater, groups by templateHash (one bucket per template variant of the pattern; each bucket carries the pattern hash, `tenx_hash`), applies a content-token Jaccard similarity threshold (≥0.85) to discriminate the matching pattern's events from look-alikes, and returns the top buckets by event count. Output marks partial extractions: per-bucket templateHash labels, recall counts, and explicit `parseFailed` markers when slot extraction fails. Multi-line group templates report head-line-only with an explicit warning. **Designed as an orchestration primitive** called by `log10x_investigate` when the chain needs concrete event evidence after a metric-tier identification. Direct user-facing use is fine but rare; prefer `log10x_event_lookup` + `log10x_pattern_trend` for single-line inspection.

Answer Log10x product questions from the docs that ship inside the MCP build (chunked + indexed at install time). Use whenever the user asks a factual product question: "what is the Receiver", "how is pattern_hash computed", "what data leaves my network", "does the Reporter modify data", instead of answering from training data. Inputs: `topic` for an exact docs-slug lookup (e.g. `faq/security/data-protection`), or `query` for natural-language TF-IDF search across those docs. `category` narrows search to one of faq / apps / engine / api / config / manage. `max_results` caps the result count (default 3). Output is a standard chassis envelope with `found`, ranked `results` (each carrying matched chunks + canonical_url), and `similar_topics` as a did-you-mean fallback. Link the `canonical_url` of each result used in the answer. The docs are shipped from `config/mksite/docs` at build time; in development the loader also honors `LOG10X_PRODUCT_KB_PATH`.

Show pipeline savings: the bytes the Receiver keeps out of the SIEM (filtering and compact) and the bytes the Retriever indexed in the customer's bucket (priced at the SIEM rate, less storage, less what was streamed back), with a dollar overlay when an analyzer $/GB rate is set (account profile list price, or per-call `effective_ingest_per_gb` override). Without a rate, the headline is percent-and-bytes only: never a fabricated $1/GB number. Use for "how much are we saving", "pipeline ROI", or "what is the Log10x stack worth financially". Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope.

Return the volume history for a single pattern over a chosen window (e.g. 1h, 24h, 7d, 30d), with a sparkline and spike detection: ranked by byte volume (with cost overlay when $/GB is set). **Call this after log10x_event_lookup** when the user asks "is this getting worse", "has it been louder before", "when did it start", or wants temporal context on a pattern surfaced in an earlier step. Always state the observation window explicitly in the reply: "flat at 2/h for the last 6 months of observation, spiked at 13:58 today", and never claim history older than the window. Pass `include` to select the cohort: `kept` (default), `dropped` (offloaded-only trend, useful for "is the receiver dropping more of this lately"), or `both` (total ingest). The envelope reports which cohort the series represents so the agent never conflates kept-only with total volume.

Given a pattern identity, generate commands to scan the user's SIEM/observability stack (Datadog monitors, Splunk saved searches, Grafana dashboards, Prometheus alert rules) for anything that depends on that pattern. **Call this before any mute, drop, or source-code deletion**: deleting a log line that feeds a live alert silently breaks the alert. Also call when a developer asks "am I allowed to delete this log.info() call" or "what references this pattern".

Run schema validation + cross-field sanity checks on a stored env-config document at `~/.log10x/envs/<env_id>.json`. **Call this** after any edit to the env doc (via `log10x_dest_set` / hand-edit / restore) or pre-flight before downstream tools that need a coherent config (commitment_report, configure_engine, offload-recipe emitters). Args: `env_id` (required, env_id UUID or nickname). Returns the canonical zod schema parse result PLUS findings across: destination.region required for vendors that need it (cloudwatch / datadog / azure-monitor / gcp-logging); ingest_url shape sanity (http(s):// prefix, splunk /services/collector suffix); streamer.url / retriever.url shape; cluster cloud type vs offload destination type alignment (eks↔s3, gke↔gcs, aks↔azure_blob); at-least-one active offload destination; SIEM region vs offload destination region (cross-region egress warning). Each finding carries severity (error / warning / info) and a remediation recommendation. Errors block downstream actions; warnings/info surface for the user.

Compare the stored env-config document against the `LOG10X_*` environment variables the env-var bridge would have produced, and report per-field disagreements with remediation recommendations. **Call this when** the user says "but I set the env var" or downstream tools report a value the user thinks they overrode: the on-prem store wins over env vars per resolver precedence, and silent-override is the most common boot-time surprise. Args: `env_id` (required, env_id UUID or nickname). For each disagreeing field (env_id, nickname, cluster.*, destination.*, streamer.*, retriever.*, offload_destinations[0].*), returns `{ field, stored, envvar, recommendation }`. The recommendation tells the user to either unset the LOG10X_* env var (preferred: on-prem store is the source of truth) or to update the stored doc via the matching setter (log10x_dest_set for destination, log10x_set_gitops_repo for gitops). Pure-on-prem-store configs (no LOG10X_* env vars set) return ok:true with an empty diff and a note that no ambiguity is possible.

Generate the customer-applied SIEM-side connector config (Datadog Forwarder Lambda, or the Splunk Add-on for AWS SQS-based S3 input) that makes a SIEM pull log10x's offload output from the customer's own S3 bucket. Call this when the user has offloaded a pattern's data to S3 (the offload action / a log10x_offload_add destination) and asks how to get Datadog or Splunk to ingest it, e.g. 'ship my offload bucket to Splunk' or 'wire Datadog to read these logs'. The MCP does not push offloaded events into a SIEM: the offload lands NDJSON in the customer's bucket, and this tool emits the pull-side connector the SIEM reads it with. Args: siem (required: datadog / splunk / both), bucket (required: the offload bucket), account_id (required), region (default us-east-1), prefix (optional, default app/), plus per-SIEM options (datadog_forwarder_arn, sqs_queue_name, sourcetype, index). Returns, per target: the discovery model, ordered setup steps, paste-ready terraform (an SNS fan-out plus IAM, and for Splunk the SQS queue and the S3-to-SNS-to-SQS notification), the SIEM-native config (the Splunk inputs.conf aws_sqs_based_s3 stanza), and verified caveats. Recipes are matched to log10x's offload output (uncompressed NDJSON, one event per line, Hive-partitioned keys) and encode the key gotcha: the offload bucket usually already notifies the 10x indexer's SQS, and S3 allows only one notification config per overlapping prefix, so both recipes fan out via SNS rather than a second raw bucket notification. Caveats: Datadog is logs-only (use log10x_backfill_metric for per-pattern metrics), and the Splunk SQS-based input collects only objects created after setup (backfill older data with a Generic S3 input). Read-only: it generates config and does not create AWS resources or mutate any env document.

Rank log patterns by byte volume and cost per pattern (bytes priced at the destination's $/GB rate when one is set), over a time range, for one service or all. Each row carries a trajectory badge (NEW, ACUTE, GROWING, STABLE or SHRINKING) read against 7, 14 and 21 day baselines. Use for "what is expensive right now", "what are the noisy patterns in <service> this hour", "give me a snapshot of my loudest events". For "what changed this week" or "did the deploy add cost", use `log10x_whats_changing`, which ranks patterns by change against a `comparison_window` baseline. Can be scoped by service label. `timeRange` accepts free-form `<n><m|h|d>` durations (e.g., `48h`, `3d`, `15m`): there's no enum snap. Pass `include` to choose which cohort to rank: `kept` (default, what the Receiver forwarded), `dropped` (the offloaded / overflow cohort alone), or `both` (total ingest pre-receiver). Use `dropped` for "what is the receiver throwing away" and `both` for an apples-to-apples pre/post comparison. Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope. REQUIRES Reporter-tier metrics. Before anything is deployed, the POC tools answer the same question from the user's own logs.

Compare which log patterns are new, gone, persistent or back again between two adjacent time windows. Compares pattern presence in two windows (the most recent `timeRange` window as "after" vs the immediately preceding `timeRange` window as "before") and returns four sets: `new` (present after, absent before), `retired` (present before, absent after), `persistent` (present in both), and `re_emerged` (flagged as new but existed prior to the before-window, the "the bug we thought we fixed is back" case, derived by checking first_seen against the before-window boundary). Plus `co_emergence_clusters`: groups of 3+ patterns whose first_seen timestamps cluster within ±co_emergence_window_seconds (default 60s). That cluster is a deploy fingerprint: no CI/CD integration required; the agent can then query the customer's deploy system externally with the cluster timestamp. The two windows compare because a pattern's hash comes from the line, the symbol library and the engine configuration, not from what a query saw: under the same engine, library and configuration the same line carries the same hash in both windows. Use for "what changed since last deploy", "which patterns disappeared this week", "did the rollback bring back the old errors", or paired with log10x_pattern_examples on a flagged hash to see slot distribution. Scoping: `service` and `severity` narrow the universe; `limit` caps rows per category. Returns structured envelope under `data.diff` with the four sets plus an `incidents` block when co_emergence clusters are detected. An engine upgrade that changes the naming rules renames the patterns it affects once: across that boundary they show as `new` and their old names as `retired`, and the frequent ones form a co-emergence cluster at the upgrade time.

Patterns ranked by delta vs a baseline window: the "what grew (or shrank) the most since X" question. Distinct from `log10x_top_patterns` which ranks by current cost; this tool ranks by delta and applies gates (`min_delta_usd`, `min_delta_contribution_pct`) that drop noise-level changes. `comparison_window: "auto"` (default) averages three offsets (1×, 2×, 3× the timeRange) for noise smoothing; specific offsets like `"7d"` compare to a single anchor, e.g. `{timeRange: "1d", comparison_window: "1d"}` is today vs yesterday (deploy-delta), `{timeRange: "7d", comparison_window: "7d"}` is this week vs last week. Brand-new patterns (no baseline samples) are EXCLUDED: they go to `log10x_whats_new` for clean separation of stories. Use for "what grew most this week", "which patterns regressed after the deploy", "what's driving cost up since yesterday". Returns patterns with per-row delta_usd, baseline_usd, current_usd, delta_pct, and a flag for whether each row crossed the contribution gate.

Patterns whose first_seen timestamp falls inside a recency window: the "what showed up recently" question. Distinct from `log10x_top_patterns` (current cost ranking) and `log10x_whats_changing` (delta vs baseline). New patterns have no baseline, so delta math is meaningless; this tool exists so they get a clean home and don't pollute the changing-vs-baseline surface. Implementation: queries bytes_per_pattern in the current `timeRange` window to find candidate hashes, then for each hash queries the 30-day history to find the earliest non-zero datapoint via `fetchFirstSeenBatch`. A pattern is "new" when its first_seen timestamp is younger than `first_seen_within` (default `1d`). Default sort: by first_seen recency descending (most recent first). Use `first_seen_within: "1h"` for incident triage, `"1d"` for daily-deploy review, `"7d"+` for weekly observability hygiene. Returns patterns with first_seen, age, cost_now_usd, bytes_now, events_now, and the service + severity attribution. An engine upgrade that changes the naming rules renames the patterns it affects once, so the first windows after it list those patterns here as new, first seen from the upgrade on.

[FRESH-SESSION ROUTING: if this is the user first cost question of the session, call log10x_start first instead, it returns the orientation menu the user needs before any per-tool action.] List every service the Log10x pipeline is watching, ranked by byte volume (with cost overlay when $/GB is set) plus per-service share of total AND the four action-axis columns (bytes_passed / bytes_offloaded / bytes_compacted / bytes_dropped) derived by joining routeState="drop" events against the cap-CSV. Pass `exception_services` to mark customer-flagged services as current_mode=pass: their next_action points at log10x_pattern_mitigate instead of log10x_configure_engine.

The contents view of the customer-owned offload S3 bucket: per-pattern bytes, event count, time-first-seen, time-last-seen, and growth rate. Filtered to action=offload via the cap-CSV the MCP wrote (`drop` patterns are NOT in S3; `compact` and `tier_down` route elsewhere). Call this as the maintenance-loop review: "what's accumulating in my overflow queue?" Routes the agent to log10x_retriever_query to fetch the offloaded events when an incident or audit needs them.

List the labels Log10x metrics can be filtered or grouped by. Call at the start of a session, or before calling any tool that takes a label/filter argument: stops the model from guessing label names like "namespace" when the label is "k8s_namespace". Pass a label name to get its distinct values.

Single-call root-cause investigation for any log line, pattern, service, or environment. Returns a complete causal chain (for acute spikes) or co-drifter cohort (for gradual drift) with confidence scores derived mechanically from data signal quality, plus ready-to-run verification commands. Per-pattern blocks include `offload_status` (pass / sample / compact / drop) so the narrative reflects whether the receiver is admitting or dropping the implicated patterns, matching `top_patterns` and `pattern_trend`. Call whenever the user asks 'what is going on with X', 'why is X spiking', 'investigate X', or pastes a log line / alert and asks for diagnosis. Input is the user's natural-language target: pass their words verbatim. The tool detects whether the input is a raw log line, pattern identity, service name, or 'environment' and runs the appropriate flow. It also detects whether the trajectory is acute or gradual drift and renders a different report shape for each. Confidence percentages decompose into named sub-scores (stat × lag × chain for acute; slope_sig × cohort for drift): walk the user through the decomposition when asked. Show the entire markdown report to the user without modification.

Identify patterns where one slot value dominates the field (>= 60% of events by default). Surfaces sampling opportunities: "slot `verb` is `get` 78% of events, sample the get case at 1/10 to cut its volume." Sampling is lossy: the other 9 in 10 of those events are discarded. Differentiated against analyzer field histograms because the engine groups by per-pattern field-set, so dominance is measured within the structural pattern, not globally. **Stage 1**: accepts events as a paste array (same shape as log10x_resolve_batch). **Calibration**: the 60% concentration floor and 1/10 sampling rate are hand-picked defaults tagged `unvalidated_default` in the output. The envelope surfaces the empirical `observed_dominant_pct_distribution` across all candidate slots so the agent can judge whether 0.6 is well above or below the noise floor for this dataset. See `docs/cross-pillar-primitives.md` for the agent behavior contract.

Templatize a batch of log events and return per-pattern triage. **This is one of two tools that run a local Log10x pipeline on the user's machine** (the other is `log10x_extract_templates`): call this whenever the user asks 'can you run log10x locally', 'do a local pipeline run', 'templatize these events', or supplies any batch to analyze (Datadog/Splunk/Elastic query results, Slack incident attachments, kubectl logs, raw text). Does NOT need Kubernetes, a deployed Reporter, or a Log10x account: the pipeline runs in-process on the host. Output structures the batch by a paste-local templateHash with per-pattern frequency + severity + full template structure + per-slot variable distribution. Each top pattern carries `actions[]` chaining to `log10x_investigate` (historical correlation) and `log10x_retriever_query` (offload retrieval). Do NOT call for single-line resolution: use `log10x_event_lookup` for that. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker.

Compile a symbol library from any mix of sources, waiting inline for the result when it is quick and handing back a pollable `job_id` when it is not. It waits up to `max_wait_ms` (default 45s): a small compile, and EVERY re-run (which reuses prior units via the pinned output folder), finishes inside that window and returns the finished library plus the full scan/link diagnostics in ONE call; a long first compile of a large tree overruns the wait and returns a running `job_id` to poll with log10x_compile_status, or just call this tool again later, since the output is pinned and a finished run is returned by the next call. `max_wait_ms: 0` returns the job_id immediately (fire-and-forget). Sources combine freely: a local folder of source code / binaries (`source_path`), GitHub repositories via the GitHub REST API (`github_repos`, with optional `github_branch` / `github_folders`), docker/OCI images (`docker_images`), Helm charts (`helm_charts`), and Artifactory artifacts (`artifactory_instance` + `artifactory_repo`, with `artifactory_files` / `artifactory_folders`). The run scans the sources (Java, Go, Python, JS/TS, Scala, C/C++, C#, plus binaries) and writes per-file `.10x.json` symbol units plus a single linked `.10x.tar` library, the AOT artifact the 10x runtime later uses to assign hidden classes (TenXTemplates) to events. GitHub pull REQUIRES a token even for public repos: pass `github_token` or set GH_TOKEN; without one the tool returns not_configured. Docker-image pull is daemonless (podman bundled in compiler-10x, `--cap-add SYS_ADMIN` granted automatically) and public images need no credentials. Helm pull is a meta-source (renders the chart, by default also pulls the images it references); OCI/URL chart refs resolve standalone while a bare `repo/chart` needs a matching `helm_repos` entry. Artifactory pull needs a token (`artifactory_token` or ARTIFACTORY_TOKEN). REQUIRES the COMPILER flavor: runs `log10x/compiler-10x @apps/compiler` by default, or a local comp

Poll an asynchronous compile started by log10x_compile (or a link started by log10x_compile_link), by its `job_id`. Returns `job_status` (running / completed / failed / timed_out), the units produced so far + the linked `.10x.tar` (path + size), elapsed time, the engine exit code, and a credential-redacted tail of the engine log. Crucially, it promotes the engine's scan/link DIAGNOSTICS into the envelope so the compiler is not a black box at 100k to 500k file scale: per-language scan-failure counts with capped failure samples (which files failed to parse and why), and the link report (units merged / skipped, files excluded by folder/name filter, and the symbol-type histogram: class / enum / log / exec). Those appear once the compiler-10x image carries the engine diagnostics change; on an older image the tool degrades to unit counts + the log tail. The first terminal poll captures the exit code into the job record and frees the container; later polls stay readable and the compiled library is never removed.

Link an existing folder of `.10x.json` symbol units (from a prior compile) into a single `.10x.tar` library, with NO source scan. This is the same compiler-flavor Compiler app invoked with link-only arguments: the units folder is the `outputSymbolFolder` and no source is mounted, so the engine reuses the units already on disk (scans 0 new files) and merges them into the library, which is written into that same folder. Like log10x_compile it waits inline up to `max_wait_ms` (default 45s; linking is usually fast, so it normally returns the linked library in ONE call) and otherwise hands back a `job_id` to poll with log10x_compile_status. Use it to re-link after editing or pruning units, to assemble a library from a units tree built piecemeal, or to rebuild a library from the output folder of a prior log10x_compile. REQUIRES the COMPILER flavor (runs `log10x/compiler-10x @apps/compiler` by default, or a local compiler-flavor `tenx` with mode="local"; an engine reporting the flavor as `cloud` is accepted, the native runtime build is refused). No Kubernetes or Log10x account needed.

Extract the structural template library from a set of log lines by running a local Log10x pipeline on the user's machine. Returns per-template records (the engine-internal templateHash + the template body with variable slots) and event count. Companion to `log10x_resolve_batch`: both tools answer 'can you run log10x locally / templatize these events'. Does NOT need Kubernetes, a deployed Reporter, or a Log10x account; the pipeline runs in-process on the host via either a locally-installed `tenx` binary or a `docker run log10x/pipeline-10x` container. Use for: (a) bootstrapping a pattern catalog before wiring up a Reporter, (b) offline auditing of stored log files, (c) validating that a config change produces expected template identities. **Validation mode**: pass `expected.min_templates`, `expected.required_patterns`, and/or `expected.forbidden_merges` to turn extraction into assertion-checked validation, each assertion reports PASS/FAIL in the output. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker. No preflight checks for it: log10x_doctor does not probe the engine.

Fetch offloaded log events from the customer's own S3 bucket by pattern hash or by a variable value, reading only the byte ranges whose Bloom filters can hold a match, without a full scan. The use case: events the Receiver offloaded to the customer's S3 bucket instead of the SIEM, over any window the bucket holds. The Bloom filters cover each event's template hash and variable values. Matched events land as a list of `*.jsonl` objects in the customer's S3; the tool returns an in-context preview (capped by `limit`) PLUS `data.results_location` (the S3 bucket + prefix holding the full object set). A capable agent reads those objects directly to answer, or hands the S3 object list to the customer's own S3-to-SIEM path. No re-ingestion pipeline, no proprietary format. The envelope additionally carries per-pattern `offload_status` so retrieval results agree with the live metric-surface disposition (pass / sample / compact / drop) without a second tool call. Call for: offloaded events of a pattern; events filtered by a variable value that is not a faceted SIEM dimension (e.g. 'all payment_retry events for customer acme-corp 90 days ago'); compliance / audit / forensic exact retrieval; confirming what the Receiver offloaded for a given pattern. Optional JavaScript `filters` refine over payloads after the Bloom-scoped fetch. For a time-bucketed series instead of raw events, use `log10x_retriever_series`. The envelope carries by_severity / by_service / by_day rollups with a rollup_basis provenance stamp (qrs_summaries = whole-match from engine summaries; events_capped = derived from the capped download).

Materialize a fidelity-aware time series from the customer's S3 offload bucket over an arbitrary window, with optional group-by on enrichment fields. Auto-selects between exact full aggregation (Strategy A) and per-window-sampled fan-out (Strategy B) based on Reporter pattern volume: small/moderate-volume queries get exact counts; high-volume / long-window queries get a sampled series with time-distribution + group-ranking fidelity preserved and tail caveats reported. Pathological volume is refused with structured narrowing guidance, never silently truncated. Call when: (a) the user wants a 'rate of pattern X over the last 30 days, broken down by tenant' answer that exceeds SIEM retention/budget, (b) a baseline needs building from cost-driver patterns where Prometheus has continuous metrics but the *grouped breakdown* lives only in the offload bucket. Use `log10x_retriever_query` instead for the event payloads (not aggregates).

Post-hoc diagnostic surface for a specific retriever query, addressed by `queryId` (returned from `log10x_retriever_query` or recovered from the S3 results prefix). Pulls the coordinator's `_DONE.json` stats (scanned / matched / streamRequests / streamBlobs / submittedTasks / expectedMarkers), counts per-worker byte-count markers under `q/<queryId>/`, lists result JSONL files under `qr/<queryId>/`, optionally filters CloudWatch events from the `queryLogGroup` for the queryId substring (when the chart's `queryLogGroup` is configured), and runs a diagnostics engine that classifies the run into states like `dispatcher_failure` (scanned=0 with submittedTasks>0), `results_not_uploaded`, or `observability_disabled`. When pod logs are reachable from the MCP host, fetches a tail and greps for the `cloud/streamer/subquery` include-resolution signature to confirm the dispatcher-failure category. Call this whenever `log10x_retriever_query` returns 0 events but the wall-clock implies scan work, or whenever an offline post-mortem needs the structured timeline for a specific queryId. Pass fetch_results: true to ALSO recover the completed results from S3 (10-event preview + counts + results_location) after a partial or timed-out query, without resubmitting.

End-to-end probe of the deployed Retriever chain. Fires a synthetic query at the picked top-volume tenx_hash (or an explicit target_hash) and asserts every stage in order: offload bucket has recent data, indexer pipeline is running (kubectl logs grep for 'starting pipeline - Tenx: @/apps/retriever/index'), SQS subquery + stream queues drained (depth ≤ 10), retriever pod containers all ready, then submits the query and asserts CloudWatch scan complete events have matched>0, CloudWatch stream worker complete events exist, S3 qr/<queryId>/*.jsonl files were written, and the MCP returned events_matched>0 AND events_returned>0. Returns a structured verdict (green / broken / unknown) with per-assert observed + remedy. Call this as the post-install verify step (chained from log10x_advise_retriever step_verify) OR as a deep doctor diagnostic when log10x_retriever_query returns 0 events and the cause is unclear. Catches the silent-failure shapes that take hours to debug manually: indexer not booted, stream pipeline launch failures, IRSA s3:PutObject misconfigured, MCP input_bucket misaligned with engine write location.

CALL THIS FIRST whenever the user asks any open-ended cost question, says save X%, asks where do I start, what should I do, how can you help: before any other tool. Detects the customer's tier (Dev CLI / Reporter / Receiver / Retriever) via three live probes (gateway auth, Reporter metric counts, Retriever resolution), detects the SIEM, and returns a structured orientation envelope with three fields the agent follows: `must_render_verbatim` (markdown to show the user as is, without summarising), `must_ask_user` (a numbered question to ask before any follow-up tool call) and `forbidden_next_actions` (tools not to call until the user has picked an option). Also returns a 5-phase journey (Visibility → Attribution → Mitigation → Forensic → Commitment) showing where the customer is, an action menu gated by available capabilities (compact_installable, tier_down_available, offload_ready, forensic_query_available), and the resolved tier. The tool is read-only, takes an optional `intent_hint` (cost / forensic / install / orient), and is safe to call on any boot state: including when no env is configured yet (skips gateway/Reporter probes and treats the customer as Dev CLI tier). Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope.

CALL THIS after the user picks 'show me what cutting costs would look like' from log10x_start. At Receiver/Retriever tier returns the 6-mode outcome-first menu (drop / sample / compact / tier_down / offload / observe_only), each gated by the customer's detected capabilities (receiver tier, SIEM type, offload bucket). At Reporter-only or Dev tier, collapses to 2 entries: observe_only + install_receiver (with prose explaining that the full 6-mode menu requires the Receiver in-path). All non-observe modes route to log10x_explain_mode. The envelope carries must_render_verbatim (show to user as-is), must_ask_user (numbered question), and forbidden_next_actions (do not call estimate_savings, configure_engine, or pattern_mitigate until the user picks). Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope.

CALL THIS AFTER log10x_cost_options when the user picks a mode. Explains the chosen enforcement mode (drop / sample / compact / tier_down / offload / observe_only) in service-level plain language, with dollar math when byte metrics are available. Returns must_render_verbatim (plain-text three-section card, no markdown), must_ask_user (Apply or Preview choice), and forbidden_next_actions (locks apply tools and log10x_preview_filter until the user picks). routes_to.apply routes all non-observe modes to log10x_configure_engine; observe_only has routes_to.apply === null (no enforcement step). routes_to.preview routes to log10x_preview_filter with { service, mode }.

CALL THIS AFTER log10x_explain_mode when the user picks Preview. Shows the list of patterns that would be affected by applying a given enforcement mode to a service, before any action is taken. Returns a fixed-width plain-text table (no markdown pipes) with columns: rank, descriptor, volume, %, service, severity, first seen, trend sparkline. Writes a CSV to /tmp/log10x-preview-<mode>-<service>.csv. must_ask_user offers: drill into pattern #N (calls log10x_pattern_detail), Apply, or go back to pick a different mode. forbidden_next_actions locks log10x_configure_engine, log10x_pattern_mitigate, and log10x_advise_retriever until the user commits.

CALL THIS AFTER log10x_preview_filter when the user drills into a specific pattern by number. Returns a full single-pattern view: 24h line chart (up to 12 rows, 72 chars wide), ASCII horizontal bar chart for cross-service byte distribution (top 8 services), severity breakdown, and up to 5 sample events truncated to 120 chars each. Requires pattern_hash (tenx_hash from preview_filter.data.patterns[].tenx_hash). must_ask_user: Back to preview list, or Apply with this in the picture. actions[]: log10x_preview_filter (back) and log10x_configure_engine (apply).

Measure per-pattern compact ratios (bytes before and after encoding) on a sample pulled from the customer's SIEM and run through a local engine; a ratio on that sample, not a SIEM meter reading. Pulls `sample_size` events for a service over `timeRange`, runs them through the local tenx engine, and returns per-pattern `compaction_ratio_x` (original bytes / encoded bytes) derived from that sample. Use this to replace the destination's default compact ratio in `log10x_estimate_savings` (one measured capture per destination, named in `compact_ratio_basis`) with ratios measured on this customer's sample. Requires: tenx CLI installed locally (LOG10X_TENX_PATH or `tenx` on PATH) AND SIEM credentials (same as `log10x_poc_from_siem_submit`). Confidence tiers: high (>=50 events), medium (10-49), low (<10). Results flow into `log10x_estimate_savings` to improve savings projections. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker.

Conversational wizard that configures a scheduled cost-reduction tick (`tenx-recur`): each run clones the policy repo, recomputes the plan and pushes the changes. Walks the user through seven decisions: target services, savings target (%), tick schedule, scheduler runtime, gitops config repo, exception services, and final confirm, then emits two ready-to-commit artifacts: `policy.yaml` (the declarative policy the tick CLI consumes) and a scheduler manifest (Kubernetes CronJob YAML, GitHub Actions workflow, or crontab entry + wrapper script depending on the chosen scheduler). Each call merges the latest answer into the wizard session and either asks the next missing question or emits the artifacts once all answers are present. Re-invoke with the same `session_id` on every subsequent turn; sessions live 30 minutes. To skip interactive Q&A, supply all fields (`target_services`, `target_percent`, `schedule`, `scheduler`, `config_plane`, `confirm: true`) in a single call. Optional overrides: `exceptions` (services never touched), `min_delta_pp` (minimum savings delta before committing a new CSV, default 2pp), `env_id`, `namespace`, `secret_name`. Datadog Standard budget: `budget_usd_monthly` (X, the whole account's Standard bill a month) replaces the savings target and makes the tick the budget run, held month to date from Datadog's estimated usage metric: on `k8s_cron` it runs in the Receiver's namespace with a service account, writes caps.csv, actions.csv, totals.csv (with a `*` row) and config-generation.csv into the policy ConfigMap and discovers node counts; on `github_actions` it commits the same files for the engine's gitops pull with `nodes_by_container`. With it: `standard_indexes`, `standard_rate_per_million`, `keep_count`, `datadog_secret_name`. The Receiver must be installed with `regulator_unit: "events"` on engine 1.1.146 or later. Elasticsearch hot tier: `hot_tier_gb` (GB of index store on the hot nodes, or `auto`) replaces the savings target; the Receiver

Run a startup health check on the Log10x MCP installation. Probes: environment configuration validity, prometheus.log10x.com reachability and auth, Reporter tier detection (Edge / Cloud / none), Retriever endpoint configuration (informational), Datadog destination credentials (informational), paste endpoint reachability, cross-pillar enrichment floor (v1.4, when LOG10X_CUSTOMER_METRICS_URL is set). Returns a markdown report with pass / warn / fail per check and remediation hints. Call this once at the start of a session to verify the install, or any time a tool returns an unexpected error to isolate whether the problem is configuration or transient.

List the user's Log10x ACCOUNT environments and report credential / login state. **Call this, and ONLY this, for any of these phrasings**: 'which Log10x environments do I have', 'which environments are available to me', 'list my envs', 'what tenants/accounts can I query', 'am I logged in', 'switch envs'. **For 'log me in' / 'sign me up' / 'create a Log10x account' / 'use my real account'**: call `log10x_signin_start` (browser Auth0 device flow; the model chains to `log10x_signin_complete` automatically), or call `log10x_signin_complete` directly with `{ api_key: "<key>" }` if the user already has a key. **Do NOT call `log10x_discover_env` for these questions**: that tool scans the user's Kubernetes/AWS infrastructure, unrelated to Log10x account environments. In demo mode (no key set, or key failed validation), the response is a step-by-step config guide. In signed-in mode, lists the user's identity, every env they can reach with permissions (OWNER/WRITE/READ), the default env, and the most-recently used env this session. Read-only, takes no args.

Takes no parameters.

Step 1 of the Log10x browser sign-in chain. **Call this for any of these phrasings**: 'sign me up for Log10x', 'create a Log10x account', 'log me in to Log10x', 'set up my Log10x account', 'switch from demo to my own data'. Requests an Auth0 device code, opens the user's browser to auth.log10x.com with the user_code pre-embedded, and returns IMMEDIATELY (no polling). Response carries `user_code`, `verification_uri_complete`, and the opaque `device_code`. **What the model MUST do after this returns**: (1) show the user the `user_code` and `verification_uri_complete` so they can verify the code in their browser matches, then (2) AUTOMATICALLY call `log10x_signin_complete` with `{ device_code: "<the device_code from this response>" }` as the next tool call. The user does NOT need to ask for that second step. **For pasted-key sign-in instead of browser**: skip this tool and call `log10x_signin_complete` directly with `{ api_key: "<key>" }`.

Takes no parameters.

Step 2 of the Log10x sign-in chain. Two mutually-exclusive paths controlled by which argument is passed. (a) **`{ device_code: "<...>" }`**: finishes the browser flow that `log10x_signin_start` began. The model should call this AUTOMATICALLY right after `log10x_signin_start` returns, passing back the opaque `device_code` from that response unchanged. Polls Auth0's `/oauth/token` until the user confirms the device authorization in their browser, then exchanges the Auth0 access token for a long-lived Log10x API key. (b) **`{ api_key: "<key>" }`**: pasted-key path, no browser. Validates the key against `/api/v1/user` and saves it. **Pass exactly one of `device_code` or `api_key`**; both or neither is rejected with a clear error. Either path writes the resolved API key to `~/.log10x/credentials` (mode 0600), hot-reloads the MCP's env list in-process, and (if `LOG10X_API_KEY` is set in the host config and would override the new file) clears that env var in-process and tells the user to remove it from their host config to make the change permanent.

Wipe the persistent credentials file at `~/.log10x/credentials` and reload envs so subsequent calls fall back to demo mode (or whichever lower-priority configuration source picks up). **Call this for**: "sign me out of Log10x", "log out", "remove my Log10x credentials", "stop using my Log10x account", "go back to demo mode". Idempotent: running it without saved credentials is a no-op. Does NOT revoke the API key on the BE; the user must do that from console.log10x.com → Profile → API Settings if they want to invalidate the key everywhere (mirrors `gh auth logout` and `aws sso logout`). If the user has `LOG10X_API_KEY` set in their MCP host config, that env var will still be active after sign-out: the tool result will flag this so the LLM can tell the user to also unset it and restart.

Takes no parameters.

Low-level PromQL passthrough to the customer metric backend configured via LOG10X_CUSTOMER_METRICS_URL. Returns the raw Prometheus response shape plus metadata about which backend served the query. This is the escape hatch for cross-pillar investigations the higher-level primitives don't cover: use it to explore the customer backend's label universe, run a one-off PromQL expression, or verify that a specific metric exists before correlating against it. For typical cross-pillar workflows, compose the deterministic primitives: `log10x_metrics_that_moved` → `log10x_rank_by_shape_similarity` → `log10x_metric_overlay`.

Auto-discover the structural join label between Log10x pattern metrics and the customer metric backend. Runs Jaccard similarity on label value sets across candidate label pairs, returns the best pair above the 0.7 threshold plus runner-ups above 0.5. The result is cached per-session keyed by (environment, customer-backend-endpoint) so the cross-pillar primitives (metrics_that_moved, rank_by_shape_similarity, metric_overlay) can auto-run this once at session start and reuse the cached join without re-probing. Agents should normally NOT need to call this tool directly: the primitives call it internally. The explicit tool exists for power users who want to inspect the join universe or force a re-discovery after backend changes. When no pair crosses the threshold, returns a structured `no_join_available` response with the full probed-label matrix and recommended next actions.

First step of cross-pillar investigation: deterministic filter on which customer metrics moved while an anchor was active. Anchor is either a Log10x pattern (`anchor_type: "log10x_pattern"`) OR a customer metric expression (`anchor_type: "customer_metric"`); candidates are all sibling series from the OTHER pillar. Partitions the anchor's window into high-phase / low-phase buckets by median rate and keeps only candidates whose mean value differs ≥15% between the two phases. Returns `moved[]`, `not_moved[]`, `evaluation_failed[]`: no Pearson, no tier, no causal framing. This is the cheap deterministic cut that pares the candidate set before the more expensive shape-similarity pass. Compose with `log10x_rank_by_shape_similarity` and `log10x_metric_overlay`.

Second step of cross-pillar investigation: Pearson correlation + signed lag on a pre-filtered candidate set (typically the `moved[]` output of `log10x_metrics_that_moved`). Returns per-candidate: `pearson_magnitude`, `pearson_signed` (direction preserved), `lag_seconds` (signed: negative = candidate leads anchor, positive = candidate lags), `lag_at_bound` (flag: peak landed at search-window boundary), `lag_tightness` (how sharply the Pearson surface peaks), `anchor_phase_gap`, `anchor_phase_aligned` (flag: candidate value differs ≥15% between anchor's high-phase and low-phase buckets), `n_buckets`. No tier, no causal label: the agent reads the flags and decides. Compose with `log10x_metric_overlay` for the final per-candidate aligned-timeseries view.

Third step of cross-pillar investigation: return aligned anchor + candidate timeseries plus deterministic facts (`peak_at`, `peak_offset_seconds`, `n_buckets_aligned`). No Pearson, no tier: pure raw data for the agent to interpret. Use this once `log10x_rank_by_shape_similarity` has narrowed to a single suspect, or to manually verify any anchor/candidate pair side-by-side. Bucket size auto-selected from window length; both series are right-aligned to the same trailing bucket grid so a sparse anchor and dense candidate compare on the same chaos window.

Kick off a full log-cost-optimization POC against the user's SIEM. Pulls a representative event sample, groups the events into log patterns, each with its pattern hash, and renders a 9-section markdown report covering top cost drivers, Receiver recommendations, ready-to-paste native SIEM exclusion configs, Compact mode potential, risk/dependency checks, and deployment paths. Supported SIEMs: cloudwatch (AWS CloudWatch Logs via IAM credential chain), datadog (DD_API_KEY + DD_APP_KEY), sumo (Sumo Logic), gcp-logging (GCP Cloud Logging), elasticsearch (Elastic Cloud / self-hosted), azure-monitor (Azure Monitor / Log Analytics), splunk (SPLUNK_HOST + SPLUNK_TOKEN), clickhouse (OpenObserve / SigNoz / custom schemas). Auto-detects the SIEM from env vars when `siem` omitted: explicitly pass `siem` if multiple credential sets exist. `scope` and `query` are SIEM-specific: CloudWatch (log group + filter pattern), Datadog (index + query), Sumo (_sourceCategory + query), GCP (project id + filter), Elasticsearch (index pattern + KQL), Azure (workspace id + KQL), Splunk (index + SPL), ClickHouse (database + SQL WHERE). For ClickHouse, also pass `clickhouse_table` (required) and column-mapping args for custom schemas (OpenObserve/SigNoz auto-detected). Returns a `snapshot_id`: poll via log10x_poc_from_siem_status to retrieve progress and the final report. Report is also written to `${LOG10X_REPORT_DIR:-/tmp/log10x-reports}/poc_from_siem-<timestamp>.md`. Default window is 7d, default target event count is 250k, default max pull time is 5 min: the pull stops at whichever of the two ceilings hits first. **Tier prerequisites**: none. No log10x API key required. **Templating defaults to privacy_mode=true**: events are templated by a local Log10x engine, either a native `tenx` CLI (install for macOS/Linux/Windows: https://doc.log10x.com/install/) or a local Docker container (set `LOG10X_TENX_MODE=docker`, auto-detected and preferred when the mode is unset), and never leave the machine.

Retrieve progress or a view of the report from a log10x_poc_from_siem_submit run. Pass `snapshot_id`; optionally `view` to select the level of detail. **In-progress** responses report status (pulling / templatizing / rendering), progress_pct, step_detail, and elapsed_seconds: poll every ~30s until done. **Complete** responses render one of six views: `summary` (default, ~30 lines, exec banner + top-5 wins + views CTA), `full` (complete 9-section report, ~300 lines), `yaml` (paste-ready Receiver mute-file for the top N patterns), `configs` (native SIEM exclusion configs, Datadog exclusion filter / Splunk props.conf / etc.), `top` (expanded N-row drivers table), `pattern` (deep-dive on one identity, requires `pattern` arg). **Failures** include partial_report_markdown when any events were successfully pulled before the error. The full report is also written to ${LOG10X_REPORT_DIR:-/tmp/log10x-reports}/poc_from_siem-<timestamp>.md regardless of which view the caller requested. Snapshots live in-memory per MCP process; a restart clears them, so persist the final report path to keep it. **Unified envelope**: response carries `status`, `query_count`, `total_latency_ms`, `backend_pressure_hint`, `human_summary`, plus the existing snapshot-lifecycle fields. Errors (unknown snapshot_id, render failure) come back as `status: 'error'` with a structured `PrimitiveError` envelope. See `docs/cross-pillar-primitives.md` for the agent behavior contract. **Two modes, and the agent should name whichever the user's phrasing invites.** This tool is the NETWORKED one: it reads the analyzer directly over the network with the caller's credentials, and the MCP mints one licence. The FENCED mode runs the same POC with no network at all: `log10x_emit_sample_plan` renders a read-only export script the user runs themselves, and the analysis happens in a container started with `--network none`, so 'cannot exfiltrate' is a kernel fact the user checks with one `docker inspect` rather than a claim

Run a log-cost-optimization POC entirely from local log sources: pass `path` for one log file (wrapper-normalized) or `paths` for files, directories and globs; `kubectl` samples pod logs; `docker` and `journald` to follow. No log-analyzer credentials required. Use when the prospect has no SIEM connection or has not yet shared API keys. Returns a synchronous markdown report with: (a) **sample composition** table, top-N pods by byte volume; the prospect must confirm the sample looks like their production mix, (b) **industry-pricing matrix**, projected savings at Datadog / Splunk / CloudWatch / Sumo / Elastic / OpenSearch list prices, NOT a prediction of any specific bill, (c) **top patterns** in the kubectl-sourced sample. For native exclusion configs, paste-ready Receiver YAML, and the full 9-section report tied to a specific log analyzer's GB-billed volume, run `log10x_poc_from_siem_submit` once credentials are available. **No automatic fallthrough**: this tool is invoked explicitly. If `log10x_poc_from_siem_submit` failed on missing credentials, the calling LLM should ask the user before re-invoking with this tool: local-source framing differs from SIEM-attached framing and silent fallthrough would be a bait-and-switch. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker. No log-analyzer credentials and no deployment are needed, but without an engine this returns an error rather than a report. Pass target_percent_reduction as a whole-number percent (e.g. 40 for 40%) to get a feasibility verdict against that target. **Two modes, and the agent should name whichever the user's phrasing invites.** Run normally, this tool reads local files but the server around it still has network. Run inside the FENCED profile (`TENX_AIRGAPPED=true`, `--network none`, the `log10x/poc` image) it is the same analysis with no network at all, and its output carries its own `docker inspect` proof. `log10x_emit_sample_plan` produces the sample for that m

Render a read-only shell script that exports a log sample out of the user's OWN log analyzer, with the user's OWN credentials, on a machine the user chooses: and then stop. This server does not run the script and, in the fenced profile, could not: it runs inside a container started with `--network none`. That split is the point. Code that sees log data has no network; code that has network is the user's own `aws` / `curl` driven by a script short enough to read once. Use this as step 2 of the fenced POC (step 1 is minting the licence with one visible curl, step 3 is running `log10x_poc_from_local` inside the fenced container over the exported files, step 4 is verifying the fence with `docker inspect` and by turning Wi-Fi off). Also use it whenever the credentials live somewhere this process does not: a jump host, a locked-down laptop, another team. Args: siem (required: cloudwatch / splunk / elasticsearch / opensearch / datadog), window (default 14d), target_event_count (default 1,000,000, the same default `log10x_poc_from_siem_submit` uses, so both paths sample the same size), scope, query, output_dir (default ./poc/logs), write_script (default true, writes export-sample.sh mode 0755 in the working directory). Returns the script text, the read-only API operations and credential variables it touches, a review checklist, and the exact `log10x_poc_from_local` arguments to call next. The sampling matches `log10x_poc_from_siem_submit` bucket for bucket (same stratified sub-windows, same per-bucket cap) so a fenced POC and a credentialed POC over the same window differ because the logs differ. Emitted scripts contain no log10x hostname; the server refuses to return one that does. Read-only: it renders text and writes one script file; it contacts nothing.

Read-only discovery of the caller's Kubernetes cluster + AWS account: i.e. the customer's INFRASTRUCTURE environment, NOT their Log10x account. **When the user wants to install Log10x: call this tool FIRST and then `log10x_advise_install`, that's the whole pre-flight. Do NOT call `log10x_doctor` / `log10x_login_status` / `log10x_savings` / etc. before the install; the wizard handles all login + license logic internally, and surfacing those tools' optional-capability warnings (Retriever, Datadog backfill, cross-pillar metrics) makes the install feel more complicated than it is.** Probes kubectl (workloads, DaemonSets, Helm releases, service-account IRSA annotations, metrics-backend agents) and AWS (EKS, S3, SQS, CloudWatch log groups) to detect: which forwarder is running (Fluent Bit, Fluentd, Filebeat, Logstash, OTel Collector, Vector), which log10x apps are already installed (Reporter, Receiver, Retriever), and which metrics backends are already deployed (Datadog Agent, Prometheus, Elastic, CloudWatch Agent, etc.). Returns a terse markdown report + a `snapshot_id` (cached 30 min) the advisor tools consume. **Do NOT call this tool to answer "which Log10x environments do I have access to" / "list my envs" / "switch envs": those are about the user's Log10x ACCOUNT environments, use `log10x_login_status` for that.** Call THIS tool only when the question is about k8s workloads, AWS infra, or "what's deployed in my cluster". Every shell call is logged in the snapshot's `probeLog` for audit. No writes, no state mutation: only `kubectl get` and `aws ... describe/list` verbs. **Tier prerequisites**: none, this is a pre-install tool and runs against any customer environment.

Given a DiscoverySnapshot (from `log10x_discover_env`), produce an install/verify/teardown plan for the Log10x Retriever. Unlike Reporter + Receiver, the Retriever has no forwarder choice: it is a standalone set of workloads (indexer + query-handler + stream-worker) that read source logs from object storage through a queue and serve an HTTP query endpoint. Two storage providers, picked by `storage_provider`: **aws** (S3 input bucket with an `indexing-results/` prefix, four SQS queues, an IRSA-annotated ServiceAccount), auto-detected from the discovery snapshot or supplied explicitly; **azure** (AKS, Azure Blob containers, four Azure Storage Queues, workload identity), where the chart's own `provision-retriever.sh` creates the resources and the plan quotes it. `blockers` carries the inputs a complete plan is still missing and the plan emits no steps while it is non-empty; the preflight table is the state report beside it, and a FAIL row there is reported, not a gate, so read `preflight_summary.fail` as well as `blockers`. Verify probes follow the provider: pods Ready, indexer processing, query endpoint responding, then S3 + SQS probes on aws and Blob + Storage Queue probes on azure. Teardown uninstalls the Helm release; on aws the S3 / SQS / IAM lifecycle stays with Terraform, on azure the last step runs the provisioning script with `--destroy` to delete the resource group it created.

Progressive install wizard for the Log10x Reporter / Receiver on Kubernetes. **This is the SINGLE entry point for installs: call it first.** Do NOT call `log10x_doctor` or `log10x_login_status` as a pre-flight; the wizard handles login state, license acquisition, and demo-mode fallback internally, and surfacing the doctor's optional-capability warnings (Retriever, Datadog backfill, cross-pillar metrics) ahead of the install confuses users with concepts that are unrelated to deploying the Reporter/Receiver. Takes a `snapshot_id` from `log10x_discover_env` and walks the user through five decisions, asking one at a time and remembering each answer across turns (the snapshot's wizard session): (1) **app**, `reporter` (dedicated DaemonSet forwarder, zero-touch) or `receiver` (sidecar inside the user's existing forwarder); (2) **forwarder**, Receiver-only, auto-picked when one is detected, asked when multiple; (3) **backends**, array of metrics destinations, can be multiple (e.g., `["log10x", "datadog"]` to report to both SaaS + own backend simultaneously); (4) **airgapped**, opt-in, conflicts only with `"log10x"` in `backends` (engine sends NOTHING to log10x.com); (5) **license_jwt**, auto-fetched from `/api/v1/license/demo` if the user is not signed in, or from `/api/v1/license` with the persisted Auth0 token if they are. Each call merges new args into the session and either asks the next question (returning a markdown prompt) or emits the final install plan once all answers are in. Demo + airgapped surfaces a soft warning (engine downgrades to online mode on demo licenses). Plan is plan-only: emits helm commands + values.yaml; the user runs them. With `log_destination: "datadog"` a Receiver plan adds the step after the POC: the fleet default for every service with no rule (`fleet_default.action` tier_down to Flex, or offload to S3), with the Flex index and its `@routeState:tier_down` filter or the S3 branch, the always-pass sample, and what an error monitor sees. With

[FRESH-SESSION ROUTING: if this is the user first cost question of the session, call log10x_start first instead, it returns the orientation menu the user needs before any per-tool action.] Two-mode savings estimator with percent-first reporting and a dollar overlay. `forecast` projects bytes_in -> bytes_out and percent reduction for a proposed plan; pass `effective_ingest_per_gb` (or rely on the account profile list-price rate) to overlay $/mo per pattern and in totals. `verify` counts realized savings from the engine `routeState` label over a window with cap-hit / drift / new-patterns / leakage attribution, leading with percent and adding the dollar overlay only when a rate is set. Without a rate, dollar fields are emitted as null (never as a fabricated $1/GB number); the envelope carries `rate_source: list_price | customer_supplied | unset` so callers can show how the overlay was derived. Accepts siem_lens (what-if destination): keeps the measured volumes, prices + gates for that destination at list rates, and stamps siem_actual vs siem_lens in the envelope. REQUIRES Reporter-tier cost attribution (per-pattern bytes in the metrics backend). Before anything is deployed, use log10x_poc_from_local or log10x_poc_from_siem_submit instead.

Pre-flight readiness gate for cost-reduction tools. Verifies Reporter age (default 7d), pattern-coverage stability, and absence of acute anomalies before configure_engine / estimate_savings should run. Returns structured `not_ready` with the specific gate(s) that failed.

Weekly aggregate against a commitment record opened by `log10x_configure_engine`. Reports delivered bytes (and dollars at the contract rate where the contract allows), projects the next 90 days from a weak Beta(2,2) prior updated with weekly evidence, and renders a markdown summary suitable for sharing. REQUIRES a commitment record opened by a prior configure_engine apply; without one there is no baseline to report against.

Weekly change report for a Datadog install, read from the per-pattern series the engine's Datadog metric output publishes (`emitted_events_summaryVolume`, tagged message_pattern, tenx_hash, k8s_container, tenx_user_service, routeState, and tenx_team once the team label ships). Lists the statements new in a service since `since` (a duration like `7d` or a date; stateless, so pass the previous report's `next_since` to continue), each with lines a day, estimated Standard indexing cost a month at Datadog list price, whether a rule held it, and the rule that did (the container's row and action in caps.csv / actions.csv, read from the gitops repo or the policy ConfigMap). Ends with proposed per-service rows in the plan's form: "<service>: any statement above N lines a day goes to Flex. Today that is these K statements, about $X a month." `view: "monitors"` instead renders two Datadog monitor definitions as JSON for the account owner to apply: a metric monitor that fires when a statement's route turns tier_down or offload, and an anomaly monitor with weekly seasonality that fires when a statement's volume rises above its weekly baseline. Read-only: Datadog's query API with DD_API_KEY / DD_APP_KEY / DD_SITE (GET only), and the engine files. Writes nothing.

Prices an account's log spikes from Datadog's estimated usage metrics, with no 10x install. Reads `datadog.estimated_usage.logs.ingested_events` (datadog_is_excluded:false, by service and datadog_index) and `datadog.estimated_usage.logs.ingested_bytes` (by service) in hourly sums over `lookback` (default `90d`). An hour is a spike hour for a service when its indexed events exceed `spike_multiplier` (default 3) times the median of the same hour over the 7 days before; consecutive hours are one spike, and a service's first 7 days set its baseline. Each spike's excess events are priced at the Standard rate (list $1.70 per million, `standard_rate_per_million` overrides) and its excess bytes at ingestion (list $0.10 per GB, `ingestion_rate_per_gb` overrides). Estimates what a fleet default limit, `headroom` (default 2) times the service's largest hour outside its spikes, would have held, as an upper bound. Returns services by spike cost, each spike (start, hours, index, excess events, cost, held), the total a year at that rate, and the caveats. With `budget_usd_monthly` (X, the whole account's Standard bill a month, optionally over `standard_indexes`), also how far over X Standard went in each calendar month, the hour it crossed, and each service's share of the overage from its share of the lines past the budget. Read-only: Datadog's query API with DD_API_KEY / DD_APP_KEY / DD_SITE (GET only). Writes nothing.

WHERE CLICKHOUSE CPU GOES: reads a ClickHouse cluster's own system tables over `days` (default 7) and reports how much of its CPU is writes and how much is reads, with no 10x install. W is the CPU of INSERTs into the logs table (`database` and `table`, default `default.otel_logs`, the ClickStack logs table) plus the CPU of its merges, over node CPU, with TTL merges reported apart. Q is SELECT CPU over node CPU, with the ten query shapes (normalizeQuery) that cost the most CPU, each with its user and count. Also returns the peak hour over the mean and W in that hour, rows and bytes written per table, bytes stored and the compression ratio per table, and the tables in the database that no SELECT read in the window. Insert and SELECT CPU come from system.query_log, merge CPU from system.part_log, and node CPU from system.metric_log, else system.asynchronous_metric_log, else the sum the logs attribute; the report says which. On ClickHouse Cloud the system logs are read across replicas with clusterAllReplicas (`cluster`). A system table the user cannot read is named with the GRANT it needs, and the rest of the census still runs. Computes no dollars: the autoscaler's response and the bill are not in system tables. Pass the measured W as `compute_write_share` to log10x_estimate_savings. Every SQL statement sent is in the result. Read-only: CLICKHOUSE_URL with CLICKHOUSE_API_KEY, or with CLICKHOUSE_USER and CLICKHOUSE_PASSWORD. Writes nothing.

[FRESH-SESSION ROUTING: if this is the user first cost question of the session, call log10x_start first instead, it returns the orientation menu the user needs before any per-tool action.] Given one pattern (symbolMessage identity or tenx_hash), return the env-gated CAPABILITY MENU of which mitigation paths are reachable: drop_at_analyzer, drop_at_forwarder, mute_at_10x, compact_at_10x. Each option carries `enabled` (true/false), `label`, and `disabled_reason` when not reachable. This is a REACHABILITY-FIRST router: it answers "which of the four tiers can I use right now given my env wiring", NOT "how much would each save". Per-option estimated savings (% reduction, $/mo) and paste-ready config snippets are surfaced by the next-tool chain (log10x_cost_options for the action menu, then the specific action tool for the snippet): NOT this envelope. The agent surfaces the menu to the user; the user picks; chain to log10x_cost_options for the action-level breakdown. **Action-shaped tool: calibration honesty**: the envelope's `recommendation_basis` tells the agent WHERE the capability detection came from (envs.json, snapshot, env vars, or unknown). `recommendation_audit.capability_sources` carries the per-field source, and `snapshot_age_seconds` carries snapshot staleness. The agent SHOULD NOT auto-route to the chosen sub-tool until the user picks an option, and SHOULD verify the basis before treating capability detection as authoritative (e.g., a stale snapshot may mis-flag mute as enabled when the receiver was uninstalled). See `docs/cross-pillar-primitives.md` for the agent behavior contract. **Call this** when a previous tool surfaced a high-cost pattern and the user asks 'what should I do' / 'how do I drop this' / 'how do I reduce this'.