Kiro MCP Server

Read Kiro session events

kiro_events

Read-onlyIdempotent

Reads normalized events after a cursor from a session or headless job feed—agent text, tool calls, plans, permissions, turns, and config changes—and long-polls for updates, returning the next cursor.

Instructions

Read normalized events after cursor from a session's (or headless job's) event feed: agent text, tool calls, plan updates, permission requests, turn boundaries with credits, mode and config changes, steering, workflow, and notices. Long-polls up to wait_s when nothing is newer. A message or tool call that changes is re-sent with a new seq: keep the latest per segment or toolCallId. Thoughts are left out unless include_thoughts. Returns next_cursor, lowest_cursor (gap: true when older events were dropped), the turn status, and pending permissions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "kiro_events"
  }
}

Input Schema

Name	Required	Description
`limit`	No
`cursor`	No
`job_id`	No
`wait_s`	No	Seconds to wait (default 0, max 55).
`session_id`	No	Kiro session id (sess_<uuid>).
`include_thoughts`	No

Output Schema

Name	Required	Description	Default
`gap`	Yes
`job`	Yes
`turn`	Yes
`events`	Yes
`job_id`	Yes
`status`	Yes
`session_id`	Yes
`next_cursor`	Yes
`lowest_cursor`	Yes
`omitted_thoughts`	Yes
`pending_permissions`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Nov 5, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description still adds substantial behavior: re-sent events with new seq requiring dedup by `segment` or `toolCallId`, thoughts excluded unless include_thoughts, gap detection via lowest_cursor, and a 55s long-poll ceiling. That is meaningful context beyond the structured fields. Missing is what happens when both or neither of session_id/job_id is supplied.

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 operation, then progressively adds polling, dedup, and filtering semantics; almost every clause carries information an agent needs. The closing sentence listing next_cursor/lowest_cursor/turn status/pending permissions partly restates an existing output schema, though the gap flag does add value.

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

Completeness4/5

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

An output schema exists and annotations cover the safety profile, so the description only needs to cover operational semantics — polling, dedup, filtering, gaps — which it does well. The remaining holes are the undocumented `limit` parameter and the unspecified mutual exclusivity of session_id and job_id.

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?

With only 33% schema coverage, the description must compensate and largely does: it explains the cursor resume point, wait_s long-poll semantics, include_thoughts filtering, and that the feed may be a session or a headless job (covering the session_id/job_id duality). The `limit` parameter is left entirely unexplained in both schema and description.

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

Purpose4/5

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

States a specific verb and resource — 'Read normalized events after `cursor` from a session's (or headless job's) event feed' — and enumerates the event kinds covered (agent text, tool calls, plan updates, permission requests, turn boundaries). An agent knows exactly what it gets. It stops short of naming the sibling it differs from (e.g. kiro_stream_session or kiro_session_history), so the distinction must be inferred.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: 'Long-polls up to wait_s when nothing is newer' tells the agent this is a polling loop, and the cursor/next_cursor contract implies resumption. There is no explicit when-to-use versus kiro_stream_session, kiro_session_history, or kiro_session_export, and no guidance on choosing between session_id and job_id.

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