Skip to main content
Glama

poll_events

Fetch new subscribed events incrementally using a timestamp and sequence cursor, returning updated cursors and warnings when buffered events were dropped.

Instructions

轮询拉取已订阅的新事件(增量游标)。首次传 since_ts=0;之后传上次返回的 next_since_ts / next_since_seq。 响应含 dropped(缓冲累计淘汰数);无新事件但淘汰增加时附 warning 提示。

Args: since_ts: 游标时间戳(首次 0;之后用上次返回的 next_since_ts) since_seq: 游标序号(同秒事件区分;用上次返回的 next_since_seq) limit: 本次最多返回条数(默认机器人侧配置) subscription_id: 可选,只返回该订阅声明类型的事件(subscribe_events 返回的 ID)

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": "poll_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
since_tsNo
since_seqNo
subscription_idNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does disclose real behavioral traits beyond the schema: the response carries 'dropped' (cumulative buffer evictions) and a warning is attached when evictions increased but no new events arrived — i.e. silent data loss is surfaced. It omits whether the call blocks/long-polls, ordering guarantees, and rate limits.

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 purpose and the cursor protocol are front-loaded, then a compact Args block covers each parameter. A small amount of repetition between the cursor protocol and the Args entries, but nothing is padding.

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 stateful polling tool the essential contract — bootstrap value, cursor chaining, optional scoping, and the eviction/warning edge case — is all present, and an output schema exists so return shapes need not be restated. Behavior on an invalid or expired subscription_id and blocking semantics are the remaining gaps.

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

Parameters5/5

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

Schema coverage is 0%, yet all four parameters are explained in the description: since_ts and since_seq are defined as cursors fed from the prior response (with since_seq disambiguating same-second events), limit defaults to bot-side configuration, and subscription_id is optional and sourced from subscribe_events' return value. This fully compensates for the empty schema descriptions.

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 description states a specific verb and resource ('轮询拉取已订阅的新事件') and qualifies it as an incremental-cursor read, which is enough to tell it apart from one-shot readers like recent_messages. It does not explicitly name a sibling it replaces, so it stops short of the top score.

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 an explicit bootstrap protocol ('首次传 since_ts=0;之后传上次返回的 next_since_ts / next_since_seq') and notes subscription_id is optional and scoped to one subscription's declared types. There is no when-not guidance or named alternative (e.g. recent_messages) for the non-subscription case.

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