Yokozuna MCP gives coding agents programmatic access to Sumo Logic logs for searching, triaging, monitoring, and schema analysis — without leaving the editor.
Core Search
Run searches (sumo_run_search): Execute Sumo Logic queries in one call with support for relative or absolute time ranges, output verbosity levels (summary, compact, full, raw), field projection, deduplication, and JSON extraction.
Bulk export (sumo_export_results): Stream up to 100,000 results to an NDJSON file on disk.
Low-level search job primitives: Manually create, poll status, page messages/records, and delete search jobs for fine-grained control.
Triage & Diagnostics
Error digest (sumo_error_digest): Auto-detects severity signals, deduplicates errors by normalized signature, and returns top problems with counts, timestamps, and sample request IDs.
Trend analysis (sumo_trend): Bucket logs over time with timeslice sparklines, split by auto-detected severity or a custom dimension.
Poll for new logs (sumo_new_since): Stateless cursor-based polling for logs arriving by receipt time, ideal for continuous monitoring loops.
Schema & Discovery
Facet exploration (sumo_facets): See log data distribution via ranked top-N counts across multiple dimensions (native Sumo fields or JSON paths).
Deep schema learning (sumo_describe_schema): Stratified-samples a scope to enumerate JSON keys with fill percentages and inferred types, and proposes paste-ready severity filter fragments.
Alerting & Monitoring
List monitors (sumo_list_monitors): Discover Sumo Logic Monitors with name, folder, type, enabled status, current state, and notification destinations.
List fired alerts (sumo_list_alerts): Query fired-alert history from the System Event Index, correlating fire and resolve events with monitor join keys.
Configuration: Credentials and deployment region are set via environment variables (SUMO_ACCESS_ID, SUMO_ACCESS_KEY, SUMO_DEPLOYMENT).
Provides tools for searching, querying, and managing Sumo Logic logs via the Search Job API, enabling incident triage and log analysis directly from the editor.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yokozuna-mcp search for errors in production logs from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Yokozuna MCP (Model Context Protocol) gives coding agents (Claude Code, Claude Desktop, …) programmatic access to Sumo Logic logs via the Search Job API — so issues in preview deployments and production can be found and triaged without leaving the editor.
Transport: stdio (local, per-developer; credentials via env vars)
Deployment default: EU (api.eu.sumologic.com), configurable
Token-economical by default: lean output with explicit levers (detail, fields,
dedupe), bulk data goes to files instead of your context window
Zero-config & schema-learning: only SUMO_ACCESS_ID + SUMO_ACCESS_KEY are
required. Severity schemas vary per system — the triage tools auto-detect each
scope's severity signal at call time and disclose exactly what they applied
(predicate, provenance, matched-N-of-M); sumo_describe_schema learns any scope's
schema in depth and proposes paste-ready filters. No schema config exists, on purpose.
Requires Node.js >= 20 and a Sumo Logic Enterprise access ID/key pair (ideally a
read-only service account). The package is on npm — npx -y yokozuna-mcp fetches and
runs it, so registering it in your MCP client is the whole install.
claude mcp add yokozuna --env SUMO_ACCESS_ID=suXXXX --env SUMO_ACCESS_KEY=<key> --env SUMO_DEPLOYMENT=eu -- npx -y yokozuna-mcpAdd --scope user to make it available in every project. Verify with claude mcp list.
Add to ~/.codex/config.toml (or use
codex mcp add yokozuna --env SUMO_ACCESS_ID=suXXXX --env SUMO_ACCESS_KEY=<key> -- npx -y yokozuna-mcp):
[mcp_servers.yokozuna]
command = "npx"
args = ["-y", "yokozuna-mcp"]
[mcp_servers.yokozuna.env]
SUMO_ACCESS_ID = "suXXXX"
SUMO_ACCESS_KEY = "<key>"
SUMO_DEPLOYMENT = "eu"Other clients (Claude Desktop, .mcp.json, from-source) are covered in the
installation docs.
Related MCP server: mcp-server-logs-sieve
The server does not read a .env file by itself — pass variables via the MCP
client's env block (as above).
Var | Required | Default | Notes |
| yes | — | Access ID. |
| yes | — | Access key. Never logged or echoed. |
| no |
| One of |
| no | derived | Explicit API base URL override; takes precedence over |
| no |
| UI origin for "open in Sumo UI" deep links, e.g. |
All remaining variables (output tuning, export dir, keepalive, facet defaults) are in the configuration docs.
Full documentation — the 14-tool reference, the querying & schema-learning workflow, monitoring, troubleshooting, and development — lives at https://yokozuna-mcp.readthedocs.io/.
Creates a search job and returns its id WITHOUT waiting. The server background-polls created jobs (keepalive) so the job persists across your tool calls; without that, Sumo cancels jobs after a short idle period. Page results with sumo_get_messages / sumo_get_records; always call sumo_delete_search_job when done. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| query | Yes | Sumo Logic query text. | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits: async creation, keepalive polling, and cleanup requirement. However, the annotations set readOnlyHint=true, contradicting the description's claim that it creates a job (a mutation). This is a serious inconsistency.
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 two focused sentences covering action, behavior, lifecycle, and parameter constraints. No unnecessary words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 1 required, no output schema, the description covers the job lifecycle (create, keepalive, page, delete), time range options, and notes on polling. It lacks explicit mention of the return format or error cases, but is otherwise thorough.
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?
With 100% schema coverage, baseline is 3, but the description adds value: explains `last` units (s/m/h/d), `from`/`to` formats (ISO-8601 or epoch ms), mutual exclusivity, and practical tips like `byReceiptTime` for recent windows. It enhances understanding beyond schema descriptions.
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 clearly states the action: 'Creates a search job and returns its id WITHOUT waiting.' It distinguishes from siblings like sumo_get_messages, sumo_get_records, and sumo_delete_search_job by being the initiation step that returns immediately.
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 provides explicit guidance: page with sumo_get_messages/sumo_get_records, delete with sumo_delete_search_job, and time range constraints (exactly one of `last` or both `from`/`to`). It lacks direct comparison with alternatives like sumo_run_search but still gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a search job, freeing its slot against the 200-active-jobs org cap. Always delete jobs you created via sumo_create_search_job (or kept with keepJob: true) when done. Deleting an already-gone job is not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Search job id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that deletion frees a slot and that deleting an already-gone job is not an error (idempotent). Annotations already indicate idempotentHint:true, but description adds vital context about the cap and cleanup practice.
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 efficient sentences with no wasted words. Purpose, usage guidance, and behavioral detail are all front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description fully explains its effect, idempotency, and proper usage context.
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?
Only one parameter 'id' with schema description 'Search job id.' Schema coverage is 100%, and description adds no further meaning beyond that already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a search job and frees a slot against the 200-active-jobs cap. It distinguishes from siblings like sumo_create_search_job and sumo_get_search_job_status by being the delete operation.
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 advises to always delete jobs created via sumo_create_search_job or kept with keepJob:true. Provides context about the cap but does not explicitly mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Thorough schema learner — the deep counterpart to the lite auto-detection inside sumo_error_digest/sumo_trend: STRATIFIED-samples the scope (per category × type/stream stratum, spread across message shapes — never first-N rows), enumerates top-level AND nested JSON keys (fill %, inferred types incl. float-strings, top values; arrays marked []), characterizes string payloads (format + severity-ish token hits) instead of returning an empty schema, breaks fields out per stratum, and closes with RANKED paste-ready severity fragments for the filter= param — each with honest caveats. It PROPOSES, never decides: it applies no filters and persists nothing; record what you confirm in your own memory. Use when a digest disclosed no-signal/zero-match or on first contact with a new system. Job budget: 2-4 aggregate jobs + 1-6 bounded page jobs, all auto-deleted. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| query | Yes | Scope query (keywords + metadata filters; no | operators). | |
| maxDepth | No | Nested-key flattening depth (default 4); arrays marked []. | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| sampleSize | No | Messages sampled for key enumeration (default 200, cap 1000). | |
| stratifyBy | No | Explicit stratification field: an absolute JSON path from the _raw root (e.g. log.type, stream). Default: auto-detected (log.type, then stream, then category-only). | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds extensive behavioral context beyond annotations: 'PROPOSES, never decides', auto-deletion of jobs, stratified sampling strategy (not first-N), and honest caveats on output. Annotations only indicate readOnlyHint=true, which is consistent.
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 relatively long but well-structured with clear sections. Every sentence provides value, though it could be slightly more compact. The use of colons and lists aids 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?
Given the tool's complexity (9 parameters, no output schema), the description is thorough: covers sampling, output format hints (ranked severity fragments), budget, and parameter relationships. No missing critical context.
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% with descriptions for all 9 parameters. The description adds extra usage context like mutual exclusivity of time parameters and default auto-detection for stratifyBy, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a 'thorough schema learner' and 'deep counterpart' to lite detection in siblings. It details stratified sampling and key enumeration, and distinguishes itself by being 'propose-only' and never deciding.
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 usage guidance: 'Use when a digest disclosed no-signal/zero-match or on first contact with a new system.' Also specifies budget and time range constraints, implying when not to use (when a quick schema suffices).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-call triage: finds the scope's severity-signal messages, groups them by normalized signature (timestamps/UUIDs/hex/numbers stripped), and returns the top-N distinct problems with count, first/last occurrence, a sample request_id for cross-referencing, and the _sourcecategory. The severity filter is AUTO-DETECTED per scope (severity schemas VARY per system) and DISCLOSED in the output with a matched-N-of-M line — override with filter=; run sumo_describe_schema on a new/odd scope for paste-ready fragments. Cost: 2 search jobs (3 when string-payload categories are in scope; 1 with filter=), all auto-deleted. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| limit | No | Top-N signatures to return (default 20). | |
| query | No | Base scope query (default: _sourcecategory=<SUMO_DEFAULT_SOURCE_CATEGORY — not set>). Scope by _sourcecategory, NOT by a hostname keyword — errors/exceptions carry no hostname and would be silently excluded. The severity filter is appended automatically — do not add | operators. | |
| filter | No | Optional raw Sumo fragment appended verbatim after the scope: keyword/paren terms (e.g. ("[error]" OR "[crit]")) or an operator chain starting with | (e.g. | json field=_raw "log.severity" as s nodrop | where num(s)>=3 or s="Fatal"). Supplying filter SKIPS auto-detection (exactly 1 search job) and is disclosed as agent-supplied. sumo_describe_schema proposes paste-ready fragments. | |
| maxScan | No | Max messages to scan for grouping (default 5000, cap 100,000). Counts cover the scanned prefix when truncated. | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint annotation, the description discloses cost (2 search jobs, 3 for string-payload, 1 with filter), auto-deletion, and auto-detected severity disclosure in output. No contradictions with 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?
The description is lengthy but each sentence adds necessary information. It is front-loaded with the core purpose and efficiently covers cost, time range, and behavioral notes. Slight room for tighter wording, but overall well-structured.
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 fully explains the return: count, first/last occurrence, sample request_id, _sourcecategory, and severity disclosure. Also covers edge cases (string-payload, filter behavior) and constraints (time range, scope query).
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?
All parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by explaining defaults (query, limit, maxScan), mutual exclusivity of time params, and filter's effect on cost. This extra context justifies a 4.
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 clearly states it provides a deduplicated error/warning digest with auto-detected severity, grouping by normalized signature, and top-N problems. It distinguishes itself from sibling tools like sumo_run_search and sumo_get_messages by emphasizing its triage purpose and aggregated output.
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 usage guidance: use for triage, consider sumo_describe_schema for new scopes, specify time range exactly one of 'last' or 'from'/'to', and avoid hostname in scope query. Also explains when to use filter to skip auto-detection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs a search and streams ALL results (up to the 100,000 server cap) to an NDJSON file on disk, returning the file path — NOT the content. Use this for bulk analysis ("feed the logs to a coding agent") instead of large inline limits. Each line is one flattened log object (metadata + parsed _raw log.* fields). Lines are CHRONOLOGICAL (oldest→newest by _messagetime; the server appends "| sort by _messagetime asc" to non-aggregate queries — a PARTIAL result may not be fully ordered). Aggregate queries export their records instead (one JSON record per line, query order; maxMessages/extract do not apply). If more than 100k messages match, split the time range into multiple exports. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| query | Yes | Sumo Logic query text. | |
| extract | No | Optional per-field JSON extraction: alias → path under _raw, e.g. {"status":"log.status","user":"log.context.user"}. Appends one `| json field=_raw "<path>" as <alias> nodrop` clause per entry (chained; never the broken comma multi-extract form). Aliases must be simple identifiers; non-aggregate queries only. Extracted aliases join the flattened field namespace (combine with `fields` or ndjson/export lines). | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| maxMessages | No | Stop after this many messages (default 100,000). | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly details behavior beyond the annotations: streaming to file, 100k cap, chronological ordering with caveats for partial results, aggregate query handling, and time range requirements. It also explains extraction mechanics and the interaction of maxMessages. This far exceeds the minimal behavioral disclosure from annotations (readOnlyHint=true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured paragraph that front-loads the core purpose ('Runs a search and streams ALL results...') before diving into details. It is slightly lengthy but every sentence adds value, and the information density is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nested objects, no output schema), the description covers all essential aspects: behavior, return value, ordering, aggregate vs. non-aggregate, extraction, time range options, cap, and receipt time. There are no obvious gaps; the description is sufficiently complete for an AI agent to use the tool correctly.
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?
Although schema coverage is 100%, the description adds significant meaning: it clarifies that time range must be exactly one of `last` or both `from`/`to`, explains the extra `| sort by _messagetime asc` appended to non-aggregate queries, details the extraction alias format and chaining, and notes the default and cap for maxMessages. These insights go well beyond the schema descriptions.
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 clearly states the tool's action: 'Runs a search and streams ALL results... to an NDJSON file on disk, returning the file path — NOT the content.' It uses a specific verb ('export') and resource ('results to a file'), and distinguishes from sibling tools by contrasting with 'large inline limits' and implying that other tools return content 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 description explicitly says 'Use this for bulk analysis... instead of large inline limits,' providing a clear when-to-use scenario. It also advises splitting time ranges if more than 100k messages match, which is a good usage constraint. However, it does not name specific sibling alternatives, so the guidance is slightly less explicit than ideal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The fastest way to see the SHAPE of matching logs before reading any messages: runs one small "count by " aggregate per dimension (concurrently; every job auto-deleted) and returns a compact ranked table per dimension. Dimensions starting with "_" are native Sumo fields (e.g. _sourcecategory, _sourcehost); anything else is an ABSOLUTE JSON path from the _raw root (e.g. stream, log.levelname, log.status — dots allowed). A dimension that is 100% (none) probably does not exist at that path — run sumo_describe_schema to learn the scope's real fields. Numeric keys match numerically when filtering (num(x) = 404) — some producers emit float-strings like "404.0" (displayed coerced). One failing dimension yields an error line, never a total failure. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| limit | No | Top-N values per dimension (default 15, max 100). | |
| query | Yes | Sumo Logic scope query (keywords + metadata filters). Scope only — no | operators; each dimension appends its own "| count by". | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| dimensions | No | Dimensions to facet on (default ["_sourcecategory","_sourcehost"]). One concurrent search job each. | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true. The description adds behavioral details: concurrent execution, auto-deletion of jobs, error tolerance (one failing dimension yields error line, not total failure), time range rules, and numeric matching behavior. This goes well beyond annotations, though rate limits or authentication are not mentioned.
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 well-structured: begins with core purpose, then details dimensions, numeric matching, and time range. It is dense but not wasteful. Slightly longer than minimal, but every sentence adds necessary context for correct usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 100% schema coverage, and no output schema, the description covers behavioral aspects well: error handling, dimension interpretation, time rules. It does not describe the return format (likely a list of facets), but the overall completeness is high for a faceted query 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 100% (all parameters described). The description adds significant meaning: explains that dimensions starting with '_' are native fields, others are JSON paths; clarifies time range exclusivity; notes default and max for limit; and explains numeric matching quirks. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'the fastest way to see the SHAPE of matching logs before reading any messages' and specifies it returns ranked top-N counts per dimension. It distinguishes from siblings like sumo_run_search (general search) and sumo_trend (time-series) by emphasizing speed and dimensionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use (fast overview before reading), what it does (concurrent jobs, auto-deleted), and how to interpret dimensions. It also suggests sumo_describe_schema for unknown fields. However, it does not explicitly state when not to use this tool versus alternatives, which would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pages messages of a NON-aggregate search job (aggregate jobs 400 — use sumo_get_records). Page size max 10000. Partial results are pageable while the job is still gathering. Token levers: detail=summary (whole-job counts by the AUTO-DETECTED severity field — exact via a side-aggregate with disclosed provenance, or a loud SAMPLE label if that fails — plus a compact histogram and top message signatures; cheapest) | compact (timestamp, level, request_id, _sourcecategory, FULL message, plus method/path/status when present) | full (compact + duration_s/logger/client_ip) | raw (verbatim _raw — logs exactly as the app emitted them, including anything sensitive it logged). See the fields/dedupe/maxMessageChars params for projection, grouping, and the message-length cap.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Search job id. | |
| sort | No | Order of returned messages by _messagetime (default "asc" = oldest→newest, best for tracing). Client-side: orders only the RETURNED result set — raise limit or narrow the query for full ordering. Not applicable to aggregate records. | |
| limit | No | Page size (default 100). | |
| dedupe | No | Group repeated messages within the RETURNED page by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — rendering "first_ts..last_ts LEVEL ×N message". Raise limit for broader grouping (only fetched rows are grouped). With detail:"raw", each group keeps one verbatim _raw exemplar. | |
| detail | No | Output verbosity (default compact). | |
| fields | No | Explicit field projection from the flattened namespace (level/request_id always kept). | |
| format | No | Output mode (default text). | |
| offset | No | Start offset (default 0). | |
| maxMessageChars | No | Safety cap for the message field (default 10000); the message is never truncated by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and the description is consistent. It details behavior like page size limit, partial result paging, token lever functionality, and provenance of summary data. No contradictions.
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 information-dense but somewhat lengthy and uses compact notation (pipes, colons). It front-loads the key point but could be better structured 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?
Given 9 parameters, no output schema, and multiple siblings, the description covers pagination, detail levels, dedupe, sorting, offset, limit, maxMessageChars, and partial result behavior. It is complete for an agent to invoke correctly.
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%, but the description adds significant value by explaining token levels in detail, dedupe behavior, and sort ordering scope. It enhances understanding beyond the schema descriptions.
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 clearly states it pages messages for non-aggregate search jobs, distinguishing from sumo_get_records for aggregate jobs. The title and description both specify the resource and verb, and sibling differentiation is explicit.
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 explicitly says to use sumo_get_records for aggregate jobs and notes partial results are pageable while job is gathering. It provides context for when to use this tool but does not exhaustively cover all alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pages records of an AGGREGATE search job (non-aggregate jobs 400 — use sumo_get_messages). Page size max 10000.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Search job id. | |
| limit | No | Page size (default 100). | |
| format | No | Output mode (default text). | |
| offset | No | Start offset (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only; description adds that non-aggregate jobs cause a 400 error and page size max 10000, going 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?
Two sentences, concise, front-loaded with key info. No wasted words.
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, but description explains tool purpose and error conditions adequately. Could mention output format but not critical.
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 has 100% coverage of parameter descriptions; description adds no additional semantic info beyond what schema provides.
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?
Description clearly states it pages records of aggregate search jobs, and distinguishes from non-aggregate jobs which require sumo_get_messages. Specific verb and resource.
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 use this tool vs sumo_get_messages: aggregate jobs only; non-aggregate jobs will 400. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Polls a search job (and resets a kept job's idle timer). States: NOT STARTED / GATHERING RESULTS (in progress; partial results already pageable) / DONE GATHERING RESULTS / FORCE PAUSED (100k cap hit — results available, truncated) / CANCELLED. For aggregate queries messageCount counts scanned input; recordCount is the result count.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Search job id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: it resets the idle timer, defines all states with their implications (partial results available, truncated results, etc.), and aligns with annotations (readOnlyHint=true). No contradictions.
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 sentences efficiently deliver purpose, side effect, and state definitions. No wasted words, front-loaded with key actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers all states and their meanings, enabling the agent to understand when to proceed with result retrieval. Complex state machine is fully 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?
The input schema has 100% coverage for the single parameter 'id' with a clear description. The description adds no additional meaning beyond 'polls a search job', so 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 description clearly states it polls a search job's status and resets the idle timer. It lists all possible states, making the tool's purpose specific and distinct from sibling tools like sumo_get_messages or sumo_get_records.
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 implicitly guides usage by explaining states (e.g., GATHERING RESULTS means results are pageable) but does not explicitly state when to use this tool versus alternatives. However, the context of polling for job completion before retrieving results is clear from the list of states.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fired-alert HISTORY — the complement to sumo_list_monitors (definitions + current state): queries the documented System Event Index (_index=sumologic_system_events _sourceCategory=alerts) through the standard Search Job API. The index is enabled and searchable by default on Enterprise accounts (the same tier the Search Job API already requires). Alert create and resolve are SEPARATE events — this tool correlates them into one line per fired alert: fired-at, resolved-at (when the resolve event is in range), latest trigger status, and the monitorId + monitor name JOIN KEYS back to sumo_list_monitors. One search job, auto-deleted. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| limit | No | Max fired alerts returned (default 50). | |
| status | No | Client-side filter on trigger state (e.g. ["Critical","Warning"]; case-insensitive). By default matches the alert's LATEST state — a resolved Critical alert now shows [Normal] and is EXCLUDED. Use statusScope:"ever" for the old lifetime behavior. | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| statusScope | No | How `status` matches (default "latest"): "latest" = the alert's current/most-recent state; "ever" = any state seen across its lifetime events. | |
| monitorQuery | No | Keyword filter (e.g. a monitor-name fragment), matched full-text against the alert event JSON. | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint annotation: it queries the System Event Index, creates an auto-deleted search job, and correlates separate events. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently packs all necessary information without redundancy. While not extremely concise, every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description describes the output format (fields like fired-at, resolved-at, join keys). All parameters are covered, and the tool's behavior is fully explained. No obvious gaps.
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?
Every parameter has a schema description, but the tool description provides additional semantics: explains the mutual exclusivity of `last` and `from`/`to`, gives examples for time formats, and clarifies status filtering behavior with `statusScope`. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists fired-alert history, explicitly distinguishes it from the sibling tool sumo_list_monitors by calling it the complement, and specifies the source index and correlation logic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use this tool (historical alerts) and mentions Enterprise account requirement, time range constraints, and automatic search job deletion. It indirectly suggests alternatives by referencing sumo_list_monitors for definitions/current state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discovers the org's native Sumo Logic Monitors (the 24/7 prod alerting): name, folder path, type, enabled/disabled, current status, trigger types, and notification destinations. Read-only management-API call — no search jobs involved. Requires an access key with the "View Monitors" capability (without it Sumo returns HTTP 403). FOOTGUN: free-text query matching is NAME-ONLY, case-insensitive substring — folder paths are NOT searched (a folder name yields 0 even when monitors live under it). The query syntax also accepts monitorStatus:<Critical|Warning|MissingData|Normal|Disabled> (what the status param wraps). Fired-alert HISTORY is a different question — use sumo_list_alerts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max monitors returned per API call (default 100). | |
| query | No | Filter text (Sumo monitors-search syntax). Matching is NAME-ONLY case-insensitive substring — folder paths are not searched. | |
| status | No | Filter by current monitor status. The API has NO OR support — multiple statuses run one API call each, unioned client-side by monitor id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=true annotation, the description discloses authentication requirements (access key with 'View Monitors' capability, HTTP 403 without), query behavior (name-only substring matching), and status filtering mechanics (no OR support, multiple statuses trigger separate API calls unioned client-side).
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 front-loaded with the core purpose, then efficiently packs details including a footgun warning and cross-reference. Every sentence provides value without 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?
Given no output schema, the description explains return fields (name, folder path, type, status, triggers, notifications). It covers authentication, query limitations, and status filtering behavior. Complete and self-contained for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds substantial value: for 'query' it explains matching behavior and syntax, for 'status' it details the lack of OR support and client-side union, and for 'limit' it complements the schema. This goes well beyond the baseline for high coverage.
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 clearly states it discovers native Sumo Logic Monitors with specific fields (name, folder path, type, status, triggers, notifications). It explicitly identifies itself as a read-only management API call, distinguishing it from sibling tools like sumo_list_alerts.
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 explicit guidance on when to use this tool vs alternatives: fired-alert history is handled by sumo_list_alerts. Includes a 'FOOTGUN' warning about query matching limitations (name-only, case-insensitive substring) and explains the query syntax including monitorStatus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stateless receipt-time monitor for polling loops: returns messages that ARRIVED since your last call plus a new cursor. First call: omit since to get a baseline over lookback (default "15m"). Every response contains a cursor=<epoch ms> line — pass that value as since on the next call and the half-open windows [since, now−settleMargin) tile contiguously with no gaps or duplicates. byReceiptTime is FORCED true and the window ends 180s in the past (settle margin) so late-arriving logs are not skipped — results are complete but ~180s stale. Aggregate queries (| count …) are rejected — use sumo_run_search for those. Token levers: detail=summary (whole-job counts by the AUTO-DETECTED severity field — exact via a side-aggregate with disclosed provenance, or a loud SAMPLE label if that fails — plus a compact histogram and top message signatures; cheapest) | compact (timestamp, level, request_id, _sourcecategory, FULL message, plus method/path/status when present) | full (compact + duration_s/logger/client_ip) | raw (verbatim _raw — logs exactly as the app emitted them, including anything sensitive it logged). See the fields/dedupe/maxMessageChars params for projection, grouping, and the message-length cap.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Order of returned messages by _messagetime (default "asc" = oldest→newest, best for tracing). Client-side: orders only the RETURNED result set — raise limit or narrow the query for full ordering. Not applicable to aggregate records. | |
| limit | No | Max inline results (default 100, hard max 5000). | |
| query | Yes | Sumo Logic query text (NON-aggregate — raw messages only). | |
| since | No | Cursor from the previous sumo_new_since response (epoch ms). Omit on the first call. | |
| dedupe | No | Group repeated messages within the RETURNED page by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — rendering "first_ts..last_ts LEVEL ×N message". Raise limit for broader grouping (only fetched rows are grouped). With detail:"raw", each group keeps one verbatim _raw exemplar. | |
| detail | No | Output verbosity (default compact). | |
| fields | No | Explicit field projection from the flattened namespace (level/request_id always kept). | |
| format | No | Output mode (default text). | |
| lookback | No | Baseline window when `since` is absent, e.g. "15m", "1h" (units s/m/h/d; default "15m"). | |
| maxMessageChars | No | Safety cap for the message field (default 10000); the message is never truncated by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), description discloses forced byReceiptTime, 180s settle margin, ~180s staleness, and aggregate rejection. No contradictions.
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 but well-structured, front-loading core concept. A bit verbose in sections (e.g., detail enumeration), but every sentence adds value for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters and no output schema, the description covers window semantics, cursor use, detail levels, dedupe, field projection, and more. Sufficient for an agent to use correctly.
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?
Even though schema coverage is 100%, the description adds deep context: detail modes (summary/compact/full/raw) with exact contents, dedupe mechanism, lookback default, and maxMessageChars safety cap. Greatly enhances understanding.
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 clearly states the tool is a 'stateless receipt-time monitor for polling loops' that returns messages that arrived since the last call plus a cursor. It explicitly distinguishes from siblings like sumo_run_search by rejecting aggregate queries.
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 explicit guidance: first call omit 'since', how to pass cursor, window semantics, rejection of aggregate queries, and alternative tool (sumo_run_search). Clear when-to-use and when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Workhorse: creates a Sumo Logic search job, waits for completion, returns the first N results, and deletes the job. Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
Token levers: detail=summary (whole-job counts by the AUTO-DETECTED severity field — exact via a side-aggregate with disclosed provenance, or a loud SAMPLE label if that fails — plus a compact histogram and top message signatures; cheapest) | compact (timestamp, level, request_id, _sourcecategory, FULL message, plus method/path/status when present) | full (compact + duration_s/logger/client_ip) | raw (verbatim _raw — logs exactly as the app emitted them, including anything sensitive it logged). See the fields/dedupe/maxMessageChars params for projection, grouping, and the message-length cap.
Inline limit max 5000 — use sumo_export_results for bulk (up to 100k to a file).
Scoping in one line: filter WHERE with _sourcecategory=. Severity schemas VARY per system — let sumo_error_digest auto-detect (it discloses what it applied), or run sumo_describe_schema on a new scope and pass filter=. TRACE one request by searching its quoted correlation id with no other filters. Hostname keywords match only request logs — hunt errors by _sourcecategory. Full workflow: the "triage" MCP prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| sort | No | Order of returned messages by _messagetime (default "asc" = oldest→newest, best for tracing). Client-side: orders only the RETURNED result set — raise limit or narrow the query for full ordering. Not applicable to aggregate records. | |
| limit | No | Max inline results (default 100, hard max 5000). | |
| query | Yes | Sumo Logic query text. | |
| dedupe | No | Group repeated messages within the RETURNED page by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — rendering "first_ts..last_ts LEVEL ×N message". Raise limit for broader grouping (only fetched rows are grouped). With detail:"raw", each group keeps one verbatim _raw exemplar. | |
| detail | No | Output verbosity (default compact). | |
| fields | No | Explicit field projection from the flattened namespace (level/request_id always kept). | |
| format | No | Output mode (default text). | |
| extract | No | Optional per-field JSON extraction: alias → path under _raw, e.g. {"status":"log.status","user":"log.context.user"}. Appends one `| json field=_raw "<path>" as <alias> nodrop` clause per entry (chained; never the broken comma multi-extract form). Aliases must be simple identifiers; non-aggregate queries only. Extracted aliases join the flattened field namespace (combine with `fields` or ndjson/export lines). | |
| keepJob | No | Keep the job alive after returning (server keeps it polled; use the primitives to page more). Idle kept jobs are auto-deleted after ~10 minutes (YOKOZUNA_KEEPALIVE_IDLE_MINUTES); any access (status/messages/records) resets the idle timer. | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). | |
| maxMessageChars | No | Safety cap for the message field (default 10000); the message is never truncated by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the full lifecycle (create, wait, fetch, delete), idle timeout for kept jobs (~10 minutes), side-aggregate for detail=summary with provenance disclosure, token levers for detail levels, and the fact that sort only orders the returned set. This is rich behavior context beyond the annotations. However, note that annotations claim readOnlyHint: true, but the description describes mutation (create/delete), creating a contradiction.
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 detailed and well-structured with paragraphs and bullet-like formatting. It is front-loaded with the main action. However, it is quite long (several sentences) and might be dense for an agent. Could be slightly more concise without losing critical information, but every sentence serves a purpose.
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?
Despite no output schema, the description explains return formats (summary/compact/full/raw) and behavior like dedupe grouping. It covers time range, scoping, and references sibling tools. With 15 parameters, it provides adequate context for using the tool effectively. The lifecycle, limits, and edge cases are well addressed.
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 has 100% coverage with descriptions, but the description adds significant meaning: explains time range options (mutual exclusivity), token levers for detail (summary/compact/full/raw with details), dedupe behavior, keepJob lifecycle, maxMessageChars as safety cap, fields as projection, extract as JSON extraction, sort limitations, etc. Provides context that schema alone does not.
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 clearly states the tool's purpose: 'creates a Sumo Logic search job, waits for completion, returns the first N results, and deletes the job.' It distinguishes itself from siblings by mentioning sumo_export_results for bulk and sumo_error_digest for auto-detection of severity. The title 'Run a Sumo Logic search (create → wait → fetch → delete)' is also very specific.
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 explicit guidance: 'Inline limit max 5000 — use sumo_export_results for bulk (up to 100k to a file).' Also recommends using sumo_error_digest or sumo_describe_schema for severity detection and mentions the 'triage' MCP prompt for full workflow. Clear when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows WHEN things happened: buckets matching messages with | timeslice, counts per bucket split into series (default: the scope's AUTO-DETECTED severity field, disclosed in the output), and renders one compact sparkline + per-bucket counts per series. Use it to spot spikes and onsets before reading messages. The query must be a plain scope — no | aggregation operators (timeslice/count are appended; jobs auto-deleted). Time range: exactly ONE of last (relative, e.g. "15m", "2h"; units s/m/h/d) OR both from and to (ISO-8601 like 2026-07-02T18:28:00, or epoch milliseconds).
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | Series dimension. "_"-prefixed = native Sumo field (e.g. _sourcecategory); "none" = one total series; anything else is an ABSOLUTE JSON path from the _raw root (dots allowed — e.g. stream, log.levelname). Omitted: the scope's auto-detected severity field (disclosed). | |
| to | No | End time: ISO-8601 or epoch ms. Requires `from`. | |
| from | No | Start time: ISO-8601 or epoch ms. Requires `to`. | |
| last | No | Relative window ending now, e.g. "15m", "2h", "1d". Mutually exclusive with from/to. | |
| query | Yes | Sumo Logic scope query (keywords + metadata filters; no | aggregation operators). | |
| filter | No | Optional raw Sumo fragment applied between the scope and the timeslice (same contract as sumo_error_digest's filter=) — e.g. trend ONLY the errors using a fragment sumo_describe_schema proposed. With filter= AND an explicit by=, no detection runs (exactly 1 job). | |
| interval | No | Bucket size, e.g. "30s", "5m", "1h" (units s/m/h/d). Default: auto — the smallest nice step giving ≤40 buckets over the window. | |
| timeZone | No | IANA timezone for query-time parsing (default UTC). | |
| maxSeries | No | Max series rendered, ranked by total count (default 8; the rest merge into "(other)"). | |
| byReceiptTime | No | Search by receipt time; recommended true for very recent windows (ingestion lag). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false. Description adds that jobs are auto-deleted, timeslice/count operators are appended, and time range validation. No contradiction. Provides additional behavioral 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?
Single paragraph, relatively concise while covering purpose, usage, constraints. Front-loaded with key info. Could be slightly more structured but no wasted words.
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 10 parameters, 1 required, no output schema, description explains return format (sparkline + per-bucket counts per series) and internal behavior (auto-delete, operator appending). Covers the main use case and constraints comprehensively.
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% with descriptions. Description adds meaning: for `by`, explains default auto-detected severity field; for `interval`, default auto gives ≤40 buckets; for `filter`, references sibling tool's contract. Provides useful beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Shows WHEN things happened' and details bucketing via | timeslice, counts per series, and sparkline rendering. It clearly distinguishes from sibling tools like sumo_get_messages or sumo_run_search by focusing on temporal aggregation and visualization.
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 'Use it to spot spikes and onsets before reading messages.' It also specifies constraints: query must be a plain scope (no | aggregation), time range must be exactly one of last or from/to. Does not explicitly mention when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.2sumo_describe_schemasumo_error_digest3 fields changedInput schema / properties / filterAdded value: +{
+ "description": "Optional raw Sumo fragment appended verbatim after the scope: keyword/paren terms (e.g. (\"[error]\" OR \"[crit]\")) or an operator chain starting with | (e.g. | json field=_raw \"log.severity\" as s nodrop | where num(s)>=3 or s=\"Fatal\"). Supplying filter SKIPS auto-detection (exactly 1 search job) and is disclosed as agent-supplied. sumo_describe_schema proposes paste-ready fragments.",
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / levelsRemoved value: -{
- "description": "Levels to include (default [\"ERROR\",\"WARNING\"]).",
- "items": {
- "minLength": 1,
- "type": "string"
- },
- "minItems": 1,
- "type": "array"
-}Input schema / properties / query / descriptionPrevious value: -"Base scope query (default: _sourcecategory=<SUMO_DEFAULT_SOURCE_CATEGORY — not set>). Scope by _sourcecategory, NOT by a hostname keyword — errors/exceptions carry no hostname and would be silently excluded. The level filter is appended automatically — do not add | operators."New value: +"Base scope query (default: _sourcecategory=<SUMO_DEFAULT_SOURCE_CATEGORY — not set>). Scope by _sourcecategory, NOT by a hostname keyword — errors/exceptions carry no hostname and would be silently excluded. The severity filter is appended automatically — do not add | operators."sumo_facets1 field changedInput schema / properties / dimensions / descriptionPrevious value: -"Dimensions to facet on (default [\"_sourcecategory\",\"_sourcehost\",\"levelname\",\"status\",\"path\"]). One concurrent search job each."New value: +"Dimensions to facet on (default [\"_sourcecategory\",\"_sourcehost\"]). One concurrent search job each."sumo_get_messages1 field changedInput schema / properties / dedupe / descriptionPrevious value: -"Group repeated messages globally by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — and render \"first_ts..last_ts LEVEL ×N message\"."New value: +"Group repeated messages within the RETURNED page by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — rendering \"first_ts..last_ts LEVEL ×N message\". Raise limit for broader grouping (only fetched rows are grouped). With detail:\"raw\", each group keeps one verbatim _raw exemplar."sumo_list_alertssumo_list_monitors3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Max monitors returned (default 100)."New value: +"Max monitors returned per API call (default 100)."Input schema / properties / query / descriptionPrevious value: -"Filter text (Sumo monitors-search syntax; matched against monitor names/content)."New value: +"Filter text (Sumo monitors-search syntax). Matching is NAME-ONLY case-insensitive substring — folder paths are not searched."Input schema / properties / statusAdded value: +{
+ "description": "Filter by current monitor status. The API has NO OR support — multiple statuses run one API call each, unioned client-side by monitor id.",
+ "items": {
+ "enum": [
+ "Critical",
+ "Warning",
+ "MissingData",
+ "Normal",
+ "Disabled"
+ ],
+ "type": "string"
+ },
+ "minItems": 1,
+ "type": "array"
+}sumo_new_since1 field changedInput schema / properties / dedupe / descriptionPrevious value: -"Group repeated messages globally by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — and render \"first_ts..last_ts LEVEL ×N message\"."New value: +"Group repeated messages within the RETURNED page by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — rendering \"first_ts..last_ts LEVEL ×N message\". Raise limit for broader grouping (only fetched rows are grouped). With detail:\"raw\", each group keeps one verbatim _raw exemplar."sumo_run_search1 field changedInput schema / properties / dedupe / descriptionPrevious value: -"Group repeated messages globally by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — and render \"first_ts..last_ts LEVEL ×N message\"."New value: +"Group repeated messages within the RETURNED page by (level, signature) — timestamps/UUIDs/hex/numbers are normalized away — rendering \"first_ts..last_ts LEVEL ×N message\". Raise limit for broader grouping (only fetched rows are grouped). With detail:\"raw\", each group keeps one verbatim _raw exemplar."sumo_trend2 fields changedInput schema / properties / by / descriptionPrevious value: -"Series dimension (default \"levelname\", parsed from log.levelname). \"_\"-prefixed = native Sumo field (e.g. _sourcecategory); \"none\" = one total series; anything else parses log.<by> from the JSON payload."New value: +"Series dimension. \"_\"-prefixed = native Sumo field (e.g. _sourcecategory); \"none\" = one total series; anything else is an ABSOLUTE JSON path from the _raw root (dots allowed — e.g. stream, log.levelname). Omitted: the scope's auto-detected severity field (disclosed)."Input schema / properties / filterAdded value: +{
+ "description": "Optional raw Sumo fragment applied between the scope and the timeslice (same contract as sumo_error_digest's filter=) — e.g. trend ONLY the errors using a fragment sumo_describe_schema proposed. With filter= AND an explicit by=, no detection runs (exactly 1 job).",
+ "minLength": 1,
+ "type": "string"
+}v0.1.0sumo_create_search_jobsumo_delete_search_jobsumo_error_digestsumo_export_resultssumo_facetssumo_get_messagessumo_get_recordssumo_get_search_job_statussumo_list_monitorssumo_new_sincesumo_run_searchsumo_trendMost tools have clearly distinct purposes, e.g., sumo_create_search_job vs sumo_run_search, but the latter is a higher-level wrapper that combines create, wait, and delete, which could cause confusion. However, descriptions are clear enough to differentiate.
All tools follow a consistent 'sumo_verb_noun' pattern. Verbs like create, delete, get, list, describe, export, facets, trend, error_digest, new_since, run_search are all well-structured and predictable.
14 tools is appropriate for the server's purpose—covering search job lifecycle, data retrieval, analysis, monitoring, and alerts. The number is neither too few nor excessive.
The tool set covers core workflows: job management, data retrieval, schema analysis, triage, trends, facets, monitors, and alerts. Missing are tools for creating/updating monitors or managing saved searches, but these are not essential for typical agent interaction.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mbe24/yokozuna-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
