Skip to main content
Glama
YawLabs

@yawlabs/aws-mcp

Official
by YawLabs

aws_logs_tail

Read-only

Retrieves the newest CloudWatch Logs events from a log group over a recent time window (default 10 minutes), with optional filtering and limits. Returns each event's timestamp, log stream, and message.

Instructions

Fetch the newest CloudWatch Logs events for one log group over the last since (default 10m), via FilterLogEvents ('aws logs filter-log-events'). Returns events oldest first as {timestamp (ISO 8601 UTC), logStreamName, message (verbatim)}; any of the three is null on an event that arrived without it, which is kept rather than dropped. At most maxEvents come back (default 500, max 10000); when the window held more, the OLDEST are dropped and truncated is true. On AWS CLI 2.35.8+ the read goes newest-first and stops once it has enough, so a busy group costs a page or two -- and a truncated result reports totalEvents: null because the rest was never read. Older CLIs read the whole window (exact totalEvents); narrow since or add filterPattern if a wide window times out. logGroupName takes a bare name or a log-group ARN in the call's region; an ARN is sent as logGroupIdentifier, so a source-account ARN works from a cross-account monitoring account (AWS CLI 2.9.15+). Does not stream: call again for newer events. eventId and ingestionTime are omitted -- use aws_call for them.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sinceNoWindow to tail: '<number><s|m|h|d|w>'. Default '10m'. Example: '30m', '1h', '3d'. Must be greater than zero and at most 30 days.
regionNoOverride session region for this call.
profileNoOverride session profile for this call.
maxEventsNoMaximum events to return (1-10000). Default 500. Events come back oldest-first; when the window held more than this, the OLDEST are dropped, the newest are kept and truncated=true. On AWS CLI 2.35.8+ the read itself stops after this many events, so totalEvents is null when truncated is true; an older CLI scans the whole window and reports the exact totalEvents. Narrow 'since' or add a 'filterPattern' to make the call itself cheaper.
timeoutMsNoTimeout in milliseconds per aws CLI call (at most two per tool call). Default 60000 (60s). Raise for large windows.
logGroupNameYesLog group name, e.g. '/aws/lambda/my-fn' or '/aws/ecs/my-service' (no leading 'logs/'). A full log-group ARN ('arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/my-fn', with or without a trailing ':*') is also accepted: it is sent as FilterLogEvents' logGroupIdentifier with the ':*' removed, so it reads the group in the ARN's own account. The ARN's region must match this call's region, and ARN input needs AWS CLI 2.9.15+.
filterPatternNoCloudWatch Logs filter pattern. E.g. 'ERROR', '"stack trace"', '[timestamp, request_id, level = ERROR, ...]'.
logStreamNamesNoRestrict to specific stream names. Overrides the default (all streams in the group).
logStreamNamePrefixNoRestrict to streams with this prefix. Mutually exclusive with logStreamNames.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.5.0
    • changedInput schema / properties / logGroupName / description
      Previous value: -"Log group name, e.g. '/aws/lambda/my-fn' or '/aws/ecs/my-service' (no leading 'logs/'). A full log-group ARN ('arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/my-fn', with or without a trailing ':*') is also accepted -- the group name is extracted from it."New value: +"Log group name, e.g. '/aws/lambda/my-fn' or '/aws/ecs/my-service' (no leading 'logs/'). A full log-group ARN ('arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/my-fn', with or without a trailing ':*') is also accepted: it is sent as FilterLogEvents' logGroupIdentifier with the ':*' removed, so it reads the group in the ARN's own account. The ARN's region must match this call's region, and ARN input needs AWS CLI 2.9.15+."
    • changedInput schema / properties / maxEvents / description
      Previous value: -"Maximum events to return (1-10000). Default 500. Events are returned oldest-first; when the window held more than this, the OLDEST are dropped and the newest kept, with truncated=true and totalEvents naming the full count. Bounds the RESPONSE only -- 'aws logs tail' has already drained the whole window server-side by the time the cap applies, so narrow 'since' or add a 'filterPattern' to make the call itself cheaper."New value: +"Maximum events to return (1-10000). Default 500. Events come back oldest-first; when the window held more than this, the OLDEST are dropped, the newest are kept and truncated=true. On AWS CLI 2.35.8+ the read itself stops after this many events, so totalEvents is null when truncated is true; an older CLI scans the whole window and reports the exact totalEvents. Narrow 'since' or add a 'filterPattern' to make the call itself cheaper."
    • changedInput schema / properties / since / description
      Previous value: -"Window to tail: '<number><s|m|h|d|w>'. Default '10m'. Example: '30m', '1h', '3d'. Must be greater than zero and at most 30 days -- 'aws logs tail' drains the whole window server-side."New value: +"Window to tail: '<number><s|m|h|d|w>'. Default '10m'. Example: '30m', '1h', '3d'. Must be greater than zero and at most 30 days."
    • changedInput schema / properties / timeoutMs / description
      Previous value: -"Timeout in milliseconds. Default 60000 (60s). Raise for large windows."New value: +"Timeout in milliseconds per aws CLI call (at most two per tool call). Default 60000 (60s). Raise for large windows."
  2. Changed1 schema field changedv2.2.2
    • addedInput schema / properties / maxEvents
      Added value: +{
      +  "description": "Maximum events to return (1-10000). Default 500. Events are returned oldest-first; when the window held more than this, the OLDEST are dropped and the newest kept, with truncated=true and totalEvents naming the full count. Bounds the RESPONSE only -- 'aws logs tail' has already drained the whole window server-side by the time the cap applies, so narrow 'since' or add a 'filterPattern' to make the call itself cheaper.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 10000,
      +  "type": "integer"
      +}
  3. Changed2 schema fields changedv2.1.0
    • changedInput schema / properties / logGroupName / description
      Previous value: -"Log group name, e.g. '/aws/lambda/my-fn' or '/aws/ecs/my-service'. No leading 'logs/'."New value: +"Log group name, e.g. '/aws/lambda/my-fn' or '/aws/ecs/my-service' (no leading 'logs/'). A full log-group ARN ('arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/my-fn', with or without a trailing ':*') is also accepted -- the group name is extracted from it."
    • changedInput schema / properties / since / description
      Previous value: -"Window to tail: '<number><s|m|h|d|w>'. Default '10m'. Example: '30m', '1h', '3d'."New value: +"Window to tail: '<number><s|m|h|d|w>'. Default '10m'. Example: '30m', '1h', '3d'. Must be greater than zero and at most 30 days -- 'aws logs tail' drains the whole window server-side."
  4. First observedv1.3.2

TDQS

A4.6/5.0
Behavior5/5

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

The description goes well beyond the readOnly/destructive annotations, detailing oldest-first ordering, null-field retention, truncation semantics, CLI version differences, cross-account ARN handling, and non-streaming behavior. This is a comprehensive behavioral disclosure that an agent can act on confidently.

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?

The description is dense but front-loaded with purpose and return format. Every sentence conveys a distinct, useful fact (behavior, CLI version nuance, ARN handling, truncation). It is long out of necessity, not verbosity; no superfluous wording.

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 a tool with no output schema and significant complexity (CLI version differences, cross-account ARNs, truncation), the description thoroughly explains return shape, edge cases, and operational caveats. It leaves no essential gap for correct invocation.

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%, with highly detailed parameter descriptions already provided. The description adds extra semantic value by explaining ARN acceptance, CLI version caveats, the omission of eventId/ingestionTime, and pointing to aws_call for those fields—context not present in the schema alone.

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?

The description opens with 'Fetch the newest CloudWatch Logs events for one log group', a specific verb and resource, and names the underlying API (FilterLogEvents). It also differentiates from siblings by noting omitted fields and directing eventId/ingestionTime needs to aws_call, making its scope unmistakable.

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

Usage Guidelines4/5

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

Provides concrete usage guidance: states the tool does not stream, recommends narrowing 'since' or adding 'filterPattern' for wide windows, and explicitly routes eventId/ingestionTime requests to aws_call. However, it does not contrast with the related sibling aws_logs_query, so the when-to-use instruction is not fully exhaustive.

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