Skip to main content
Glama

wait_for

Destructive

Ends an agent turn to wait for a card, merge request, CI pipeline, registration, external event, or manual signal, then resumes the agent when that event occurs.

Instructions

End your turn waiting on an event: another card (on=card), a merge request (on=mr), a CI pipeline or GitHub Actions run (on=pipeline), the runner's merge gate on a reviewed head (on=merge), a runner registration (on=registered), the published moment of an external event (on=time, with event_ref, source and why) or, only on a card a lead labelled wake:manual, a passive wait with no observer and no timer that a new comment or the lead's action ends (on=manual, with note saying why). A GitHub PR merge is on=mr provider=github until=merged (project_path owner/repo, mr_iid the PR number, after_sha the head, after_status opened); on=merge is GitLab only. The server checks the target, records the wait (replacing your previous one on this card), writes the comment and releases your checkout; you are woken when the event happens. A refusal writes nothing. Waiting on another agent's answer is ask_agent; on a person, ask_human.

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": {
      "task_id": "<task_id>",
      "on": "<on>"
    },
    "name": "wait_for"
  }
}

Input Schema

NameRequiredDescriptionDefault
onYesWhat you wait on: card, mr, pipeline, time, merge, registered or manual. Only the fields of that kind are read; after_* and registration* on a kind that does not take them are refused.
whyNoon=time, required: what happens at until_at and why not earlier, 10 to 500 chars.
noteNoWhy you wait and what ends the wait; the generated comment shows it whole, the wait itself keeps its first 500 characters. Required for on=manual.
untilNoon=mr: merged, green or changed. on=pipeline: finished, green or changed.
mr_iidNoon=mr or merge: merge request iid within project_path (not the global id).
sourceNoon=time, required: where the event's time is published: an https:// URL, comment:<uuid> or artifact:<uuid> written by someone else. A card is not a source.
task_idYesThe card you are working on (UUID or 6-12 hex short id).
turn_idNoOptional turn id within the session (max 200 chars), copied onto the outcome.
providerNoon=mr: gitlab or github. on=pipeline: gitlab (default) or github for an Actions run (project_path owner/repo, pipeline_id the run id). on=merge: gitlab only; a GitHub PR merge is on=mr provider=github until=merged.
until_atNoon=time: when the external event happens, RFC3339 with Z or an offset (2026-10-29T06:00:00Z, 2026-10-29T09:00:00+03:00), 5 minutes to 30 days from now. Not a retry or poll interval: a wait on a card, MR or pipeline waits on that event.
after_shaNoon=merge, required: full 40 or 64 hex SHA of the reviewed head. on=mr or pipeline, optional baseline: the head SHA you observed.
criterionNoon=card with target_condition=artifact_published: the result you wait for, as its producer will name it in the evidence (max 500 chars).
event_refNoon=time, required: the external event the moment belongs to, e.g. nightly-export (max 500 chars).
session_idNoOptional runner session id (max 200 chars), copied onto the recorded outcome and wait.
pipeline_idNoon=pipeline: the pipeline id to wait on.
vcs_link_idNoon=mr: id of a VCS link of this card. Alternative to provider + project_path + mr_iid.
after_statusNoBaseline status: opened for until=merged; for until=green or changed the pipeline status you observed (running, failed, success, manual, ...).
project_pathNoon=mr, pipeline or merge: project path, e.g. entire-vc/evc-mesh.
registrationNoon=registered: ops-review, gmail, receipt, lifecycle, stall, recovery, queue or native.
required_jobsNoon=pipeline, or on=mr with until green or changed: job names to read the wait from; omit for the whole pipeline.
target_task_idNoon=card: the card you wait on. Creates or reuses a blocks dependency on it; the receipt's wait names that edge (dependency_id, dependency_generation) and dependency_owned=true only when this wait created it or took it over from your own earlier wait on this card. An edge someone else made stays theirs (dependency_owned=false), and an operator's later edit of your edge (condition change, confirmed binding) takes it from your wait; the owner-checked delete (expected_generation + expected_owner_wait_id) refuses both with 409. on=manual: optional, must be this card itself.
registration_refNoon=registered: ops-review or native: the 64-hex id; gmail: gmr_<12 hex>; receipt, lifecycle, stall, recovery, queue: this card's 8-hex id (may be omitted).
target_conditionNoon=card: what the card must reach: task_done (default), shipped, deployed, accepted or artifact_published (a named result of that card: give criterion; its owner records the evidence). A card closed without that evidence still releases the wait, marked released_by=closure_without_evidence.
after_pipeline_idNoBaseline of until=green or changed: the pipeline id you observed (on=pipeline: equal to pipeline_id). Send with after_sha and after_status.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.8
    • addedInput schema / properties / criterion
      Added value: +{
      +  "description": "on=card with target_condition=artifact_published: the result you wait for, as its producer will name it in the evidence (max 500 chars).",
      +  "type": "string"
      +}
    • changedInput schema / properties / target_condition / description
      Previous value: -"on=card: what the card must reach: task_done (default), shipped, deployed or accepted."New value: +"on=card: what the card must reach: task_done (default), shipped, deployed, accepted or artifact_published (a named result of that card: give criterion; its owner records the evidence). A card closed without that evidence still releases the wait, marked released_by=closure_without_evidence."
    • changedInput schema / properties / target_task_id / description
      Previous value: -"on=card: the card you wait on. Creates or reuses a blocks dependency on it. on=manual: optional, must be this card itself."New value: +"on=card: the card you wait on. Creates or reuses a blocks dependency on it; the receipt's wait names that edge (dependency_id, dependency_generation) and dependency_owned=true only when this wait created it or took it over from your own earlier wait on this card. An edge someone else made stays theirs (dependency_owned=false), and an operator's later edit of your edge (condition change, confirmed binding) takes it from your wait; the owner-checked delete (expected_generation + expected_owner_wait_id) refuses both with 409. on=manual: optional, must be this card itself."
  2. Addedv0.1.7

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (destructiveHint=true, idempotentHint=false) it explains the mechanism: the server checks the target, records the wait replacing your previous one on this card, writes the comment and releases your checkout, and you are woken when the event happens. It also discloses failure behavior ("A refusal writes nothing") and the kind-field strictness ("after_* and registration* on a kind that does not take them are refused"), which is exactly the context the annotations alone could not supply.

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 primary alternative routing are front-loaded in the first two sentences, and every clause carries a distinct rule rather than filler. The cost is density: the opening parenthetical enumerating all seven kinds is a long unbroken span that duplicates part of the on= parameter text, making it harder to scan than it needs to be.

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 24-parameter tool with no output schema and no enums, the description covers the selection logic, required-field dependencies per kind, wake semantics and refusal behavior — everything an agent needs to call it correctly. What it does not cover is the shape of the recorded outcome/receipt (beyond dependency_owned hints in the schema) or the error surface beyond a plain refusal.

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 the baseline is 3; the description earns above that by adding cross-parameter rules the per-field schema text cannot express — which fields are read per kind, that on=merge is GitLab-only, and the full GitHub PR merge field recipe (provider, project_path owner/repo, mr_iid as the PR number, after_sha as head, after_status opened). It stops short of adding format detail beyond what the schema already states for individual fields.

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?

"End your turn waiting on an event" is a specific verb+resource, and the description enumerates exactly which event kinds (card, mr, pipeline, merge, registered, time, manual) map to which on= value. It also names the siblings it is not (ask_agent, ask_human), so an agent can distinguish it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: waiting on another agent's answer is ask_agent, on a person is ask_human, and on=manual is permitted only on a card a lead labelled wake:manual. It also states the concrete mapping for a case an agent would otherwise get wrong ("A GitHub PR merge is on=mr provider=github until=merged", "on=merge is GitLab only").

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