Skip to main content
Glama

Read new events of a Berrys agent run

playground_run_events
Read-onlyIdempotent

Return only what changed in a run since afterSeq: compact events, a status line, pending approvals, the final response once it ends, nextAfterSeq, and retry_after_seconds (wait that long before polling again; null once the run has ended). Give runId, or conversationId for the latest run in that conversation (e.g. after reconnecting). Pass waitSeconds (up to 25) to have the server wait for new events or a status change before answering. Read-only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>"
    },
    "name": "playground_run_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of results to return in this page.
runIdNoRun ID returned by preparation or execution for this project.
afterSeqNoLast event sequence number already received; return only later events.
projectIdYesID of the Playground project chosen for this task; obtain it from project creation, an explicit project link or current context.
waitSecondsNoMaximum seconds to wait for new events or a job update; prefer long polling over repeated immediate requests. Optional long poll: wait up to this many seconds (0–25, default 0) on the server for a change before returning.
conversationIdNoConversation ID for filtering or continuing the associated agent work.

Output Schema

NameRequiredDescriptionDefault
nextNoSuggested next action; it does not authorize spending.
errorYes
runIdYes
eventsYes
statusYes
hasMoreYes
responseYes
statusLineYes
nextAfterSeqYes
conversationIdYes
pendingApprovalsYes
retry_after_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's trailing 'Read-only' is redundant. It earns credit elsewhere: it defines incremental semantics via afterSeq, explains retry_after_seconds as a server-directed backoff that becomes null at terminal state, and discloses the long-poll blocking behavior (server waits for events or a status change). Missing only error/empty-result behavior or pagination signaling.

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 response contents are front-loaded in a single dense sentence, followed by the two invocation switches (runId vs conversationId, waitSeconds) in priority order. Every clause carries information, though the parenthetical field list is packed and 'Read-only' duplicates the annotation rather than adding anything.

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?

For a six-parameter polling tool this covers the essentials: how to scope the run, how to resume from a sequence number, and the retry cadence to obey. Because an output schema exists it need not enumerate return fields, yet it does so concisely. Minor gaps remain around limit/page behavior and what a closed or errored run yields beyond the null retry_after_seconds.

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 baseline is 3. The description still adds real meaning beyond the schema: it frames afterSeq as 'only what changed' bookkeeping, clarifies that runId and conversationId are alternative entry points (schema describes conversationId only vaguely as 'filtering or continuing'), and explains waitSeconds as a bounded long-poll rather than a delay. limit/pagination is left entirely to the schema.

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?

The opening clause states a specific verb and resource: return the delta of a run's events since afterSeq. It enumerates the payload shape (compact events, status line, pending approvals, final response, nextAfterSeq, retry_after_seconds), which makes the tool unmistakable. It never names a sibling such as playground_run_diagnose or playground_run_delivery, so the agent must infer the boundary from purpose alone, keeping this at 4 rather than 5.

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?

It gives concrete invocation context: supply runId, or conversationId to target the latest run in a conversation, explicitly tagged '(e.g. after reconnecting)'. It also explains when to use waitSeconds as server-side waiting instead of immediate re-polling. It stops short of stating when-not to use it or which sibling to pick for diagnostics/history, so it is clear context without explicit alternatives.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.