Skip to main content
Glama

wait_task

wait_task
Read-only

Polls one task ID or a batch of up to 20 until a terminal or needs_user state is reached, returning status snapshots; on timeout returns current state so you can call again.

Instructions

等待任务到达停点(阻塞只读原语,合并原 wait_task / wait_any)。单任务模式:提供 taskId,轮询至终态(succeeded/failed/needs_attention/cancelled/interrupted)或 needs_user。批量模式:提供 taskIds(1..20 个,开始前校验全部存在、缺一即报错),等待数组顺序首个到达停点者,返回其快照与全部任务当前状态。两参数必须且只能提供一个。超时(timeoutMs 缺省 50000ms、上限 600000ms)后返回当前状态快照;超时返回时请再次调用本工具继续等待——本调用不影响任务本体,超时/中断均无害。

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

Input Schema

NameRequiredDescriptionDefault
taskIdNo
taskIdsNo
timeoutMsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.0.0-beta.3
    • addedInput schema / properties / taskIds
      Added value: +{
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 20,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "taskId"
      -]
  2. Addedv0.7.7

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description discloses that the call blocks and polls, the full set of terminal states, up-front validation of all taskIds (fails if any is missing), which task's snapshot is returned in batch mode, the default and maximum timeout values, and that timeout/interruption is harmless and does not mutate the task. That's exactly the behavioral context an agent needs to retry safely.

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 definition, then cleanly partitioned into '单任务模式', '批量模式', and timeout behavior, so an agent can scan to the relevant branch. Some clauses are dense (the batch-mode sentence packs validation, ordering, and return content together), but nothing is filler.

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?

For a 3-parameter blocking tool with no output schema and no schema descriptions, the definition covers what it returns (the snapshot of the triggered task plus all tasks' current status), how it terminates, and what to do on timeout. Nothing an agent needs to call or retry it correctly is missing.

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 description coverage is 0%, so the description carries the whole burden and does: it explains taskId (single mode), taskIds (1..20, all validated before waiting), the mutual-exclusion constraint that isn't expressible cleanly in the schema, and timeoutMs semantics including the 50000ms default and 600000ms cap that the schema does not state. The only small gap is that it doesn't describe taskId format.

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

Purpose5/5

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

The description gives a specific verb and resource ('等待任务到达停点' - wait for a task to reach a stopping point), labels it a blocking read-only primitive, and explicitly distinguishes the two modes (single taskId vs batch taskIds). It also notes it consolidates the former wait_task/wait_any, which tells an agent right away that this replaces two older tools.

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 mode-selection guidance (single task -> taskId, group -> taskIds with first-in-order-wins), the hard rule that exactly one of the two must be supplied, and an explicit retry protocol after timeout ('请再次调用本工具继续等待'). What's missing is any comparison to the non-blocking siblings query_task / query_info, so an agent isn't told when to poll instead of block.

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