Skip to main content
Glama

drain_events

Consume buffered probe hook events from the queue, optionally filtering by event kind across the entire queue; non-matching events stay queued in original order.

Instructions

取走探针缓冲的 Hook 事件(调用记录)。kind 过滤作用于整条队列(不是只看队首)。

不匹配的事件会原序留在队列里,不会被吞;超出 limit 的匹配事件同样留下。

语义与 AiMod 的 /v1/events?after= 一致:取走即消费。 想持续观察就每隔一会儿调用一次,累加统计即可。

kind 过滤的是整条队列,不是只看队首那一条 —— 注入后队首恒有一条 notice(probe_ready),若只在队首判断,kind="hook" 会一条都取不到 (返回 ok:true + 空列表,调用方会误判成「Hook 没触发」而去排查落点)。 不匹配的事件按原序留在队列里,不会被吞;超出 limit 的匹配事件同样留下。

Args: limit: 本次最多取多少条。 kind: 只取某类事件(如 "hook" / "notice" / "log")。

Returns: {ok, returned, pending_approx, dropped, events: [...]} 事件形如 {type, id, label, phase: enter/leave, seq, thread, from, args, retval}

Input Schema

NameRequiredDescriptionDefault
kindNo
limitNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.2/5.0
Behavior5/5

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

The description discloses the key trait the annotations only hint at: 取走即消费 (drain-and-consume), matching idempotentHint=false, plus that non-matching and over-limit events are preserved in order and never swallowed. This is exactly the behavioral nuance an agent needs before calling a consuming operation, and it is consistent with readOnlyHint=false / destructiveHint=false.

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

Conciseness3/5

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

Front-loaded with the core consume semantics, but the text repeats itself almost verbatim: the whole-queue filtering point appears three times and the '不匹配的事件留在队列里,不会被吞' sentence twice. Roughly a third of the description is redundant restatement.

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?

There is no output schema, and the description supplies the return shape ({ok, returned, pending_approx, dropped, events:[...]}) plus the event field layout. Combined with the consumption semantics and the kind-filter pitfall, an agent has everything needed to call and interpret it correctly.

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 0%, so the description must carry the burden — and it does: limit is '本次最多取多少条', kind is '只取某类事件' with example values (hook / notice / log). It additionally explains that kind filters the whole queue rather than the head, which is meaning the schema cannot convey. Defaults (200, "") are left 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?

States a specific verb and resource: 取走 (drain) the probe's buffered Hook events, with parenthetical clarification that these are call records. It is clearly distinguishable from read-only log readers, though it never names the sibling probe_log explicitly.

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?

Gives concrete usage context: '想持续观察就每隔一会儿调用一次,累加统计即可' tells the agent to poll periodically and accumulate stats. It also warns which failure mode (empty list from queue-head-only filtering) leads callers astray. It lacks an explicit 'use X instead when…' comparison against probe_log.

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