Skip to main content
Glama
YawLabs

@yawlabs/aws-mcp

Official
by YawLabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

aws_logs_query

Read-only

Run a CloudWatch Logs Insights query and get results in one call, replacing manual start, poll, and status interpretation steps.

Instructions

Run a CloudWatch Logs Insights query and wait for it to finish -- StartQuery, poll GetQueryResults until the query reaches a terminal status, return the rows -- in ONE call, replacing the three-step start/poll/interpret-status dance you would otherwise write with aws_call. logGroupNames takes 1-50 bare group names ('/aws/lambda/my-fn'); a log-group ARN is accepted and its NAME extracted, which DISCARDS the ARN's account, so a cross-account ARN queries the same-named group in your own account -- real cross-account queries need logGroupIdentifiers, which this tool does not send. queryString is Logs Insights QL, e.g. 'fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 20' or 'stats count(*) by bin(5m)'. startTime/endTime take the same vocabulary as aws_logs_tail and aws_metrics_query -- relative shorthand ('15m', '1h', '1d', '1w'), 'now', or ISO 8601 with an explicit offset -- defaulting to the last hour, and the window is capped at 90 days. Returns {queryId, status, rows, rowCount, fields, statistics, truncated, ...}: rows are FLATTENED from the API's [{field, value}] pairs into plain objects, so a row reads {'@timestamp': '...', '@message': '...', '@ptr': '...'}. statistics.recordsMatched counts everything the query matched and can be far larger than rowCount when limit (default 1000, max 10000) clipped the result -- truncated is true when it did. BILLING: Insights charges by the uncompressed bytes SCANNED, so a wide window across many log groups costs money whether or not anything matches; narrow the window and add a filter before widening either. Waits up to maxWaitMs (default 120000, max 900000) and reports one progress update per poll; on timeout or client cancellation the query is NEVER stopped -- it keeps running and the error hands back queryId, whose results stay retrievable for 7 days. For plain 'show me recent log lines' with no aggregation, aws_logs_tail is cheaper and simpler.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum rows the query RETURNS (it still scans, and bills for, the whole window). Default 1000. StartQuery's own ceiling is 100000, but a single GetQueryResults call returns at most 10000 rows and the remainder needs GetQueryResults pagination this tool does not use, so 10000 is the cap here. Check 'truncated' and 'statistics.recordsMatched' to see whether more matched than came back.
regionNoOverride session region for this call.
endTimeNoSame forms as startTime: relative shorthand, 'now', or ISO 8601 with an explicit offset. Default 'now'.
profileNoOverride session profile for this call.
maxWaitMsNoTotal time to wait for the query, in ms (range 1000-900000). Default 120000. On timeout the query is NOT stopped -- the error returns the queryId and results stay retrievable for 7 days.
startTimeNoRelative shorthand ('15m', '1h', '1d', '1w'), 'now', or an ISO 8601 timestamp with an explicit offset ('2026-05-16T10:00:00Z', '2026-05-16T10:00:00-04:00'). A date-only '2026-05-16' is read as UTC midnight; an offset-less date-time is rejected (it would resolve in the server host's local zone). A bare number like '5' is rejected -- write '5m'. Default '1h'. The window may not exceed 90 days.
timeoutMsNoTimeout for each individual aws CLI call, in ms. Default 60000. Bounds one start-query or one get-query-results, not the whole wait -- that is maxWaitMs.
queryStringYesCloudWatch Logs Insights query, max 10000 chars. E.g. 'fields @timestamp, @message | filter @message like /ERROR/ | sort @timestamp desc | limit 20', or 'stats count(*) by bin(5m)'.
logGroupNamesYes1-50 log group names, e.g. ['/aws/lambda/my-fn'] -- StartQuery caps a query at 50. A full log-group ARN is accepted and its name extracted; that discards the ARN's account, so a cross-account ARN queries the same-named group in YOUR account.
queryLanguageNoQuery language. Default CWLI (Logs Insights QL -- what the queryString examples use). 'PPL' is OpenSearch Piped Processing Language. OpenSearch SQL is deliberately not offered: it expects the log groups named INSIDE the query string rather than passed alongside it, which contradicts this tool's required logGroupNames -- use aws_call for SQL.
pollIntervalMsNoDelay between GetQueryResults polls, in ms (range 500-30000). Default 2000. The floor keeps one call inside the 10/sec account quota for this API.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.2.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover safety (readOnly, non-destructive, openWorld, non-idempotent), but the description adds materially more: per-byte SCANNED billing, the fact that a timeout or cancellation NEVER stops the query and the queryId stays retrievable for 7 days, the ARN-to-name collapse that silently breaks cross-account queries, and how `truncated` relates to `statistics.recordsMatched`. That is exactly the kind of behavior annotations cannot express.

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

Conciseness4/5

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

Front-loaded with the core one-call promise, then progressively discloses billing, error semantics, and alternatives. It is long and there is some overlap with the input schema's own descriptions, but nearly every sentence carries operational weight.

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

Completeness5/5

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

For an 11-parameter tool with no output schema, the description documents the return shape ({queryId, status, rows, rowCount, fields, statistics, truncated}), the flattened row format, and the failure mode (queryId handed back on timeout). Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains the time-vocabulary shared with aws_logs_tail/aws_metrics_query, the 90-day cap, and the account-discarding ARN behavior on logGroupNames. It slightly duplicates the schema text rather than adding new syntax detail, keeping it short of a 5.

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

Purpose5/5

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

States a specific verb and resource ('Run a CloudWatch Logs Insights query and wait for it to finish') and explicitly frames itself as a single-call replacement for the start/poll/interpret sequence done via aws_call. An agent can distinguish it from aws_logs_tail and aws_call without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: use this instead of the three-step aws_call dance, use aws_logs_tail for plain 'show me recent log lines' with no aggregation, and use aws_call for OpenSearch SQL. It also warns to narrow the window and add a `filter` before widening scope.

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

Deploy Server

Other Tools