Fetch collaboration updates in one idempotent round: heartbeat, inbox with cursor ack, available tasks, and deadline alerts. Local cursor persistence avoids duplicate processing.
幂等拉取一轮：心跳（按间隔节流）+ 收件箱（增量游标 + ack）+ 可接任务发现 + 我认领任务的到期提醒。本地持久化游标，重复调用不重复处理。
| Name | Required | Description | Default |
|---|---|---|---|
| once | No | 固定为单轮幂等执行 |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does well: idempotency, local cursor persistence, heartbeat throttling, incremental inbox cursor with ack, and no duplicate processing are all disclosed. This is rich, specific behavioral context beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire definition is one dense, front-loaded sentence that conveys the core idempotent-pull behavior first, then lists components and key constraints. Every clause earns its place and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex aggregate tool with no annotations and no output schema, the description covers the important behavioral aspects well. The main gap is that it never states what the tool returns or what failure/error behavior looks like, so an agent must infer the output shape from the enumerated data sources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter 'once' is described as '固定为单轮幂等执行', which closely mirrors the description's own idempotency claim. The description adds no meaningful semantic information beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('幂等拉取一轮' – idempotently pull one round) and enumerates the resources involved: heartbeat, inbox, available task discovery, and expiry reminders. It is clear about what the tool does, though it does not explicitly distinguish itself from closely related siblings such as zhiqi_heartbeat or zhiqi_inbox.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this tool is a repeat-safe poll round: '重复调用不重复处理' and local persisted cursor imply it is meant for repeated invocation. It does not explicitly state when not to use it or name alternatives for single-purpose operations like a standalone heartbeat or inbox fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.