Skip to main content
Glama

Wait for work

wait_for_work

Waits for the next godspeed request—lesson turn, Talk message, background job, or graph run—and returns a work item or "idle" status so agents can poll for tasks.

Instructions

Wait for the next request from godspeed (a lesson turn, a Talk message, a background job, or a knowledge-graph run). Returns a work item, or status "idle" if nothing arrived in time — then call again.

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_for_work"
  }
}

Input Schema

NameRequiredDescriptionDefault
helperNoSend true on every call when you are the helper: a second session beside the teacher, started when the user says "Start as the helper". A helper takes the background jobs (file reading, graph building, sheets), and lesson or Talk turns only while the teacher tidies its memory.
lesson_idNoStay on this lesson: take its turns and Talk messages, plus other lessons' turns no one else waits for and background jobs (file reading, graph building, research) while no helper is open, so they never get stuck.
full_contextNoSend the whole conversation and instructions again, even if you saw them before (use after losing your context).
timeout_secondsNoHow long to wait in seconds (default 45, at most 600). Stay under your client's tool timeout: for Codex that is its tool_timeout_sec (60 unless raised; the godspeed folder's start command sets 620).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.5
    • addedInput schema / properties / helper
      Added value: +{
      +  "description": "Send true on every call when you are the helper: a second session beside the teacher, started when the user says \"Start as the helper\". A helper takes the background jobs (file reading, graph building, sheets), and lesson or Talk turns only while the teacher tidies its memory.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / lesson_id / description
      Previous value: -"Stay on this lesson: take its turns and Talk messages, plus background jobs (file reading, graph building, helpers) so they never get stuck. Other lessons wait."New value: +"Stay on this lesson: take its turns and Talk messages, plus other lessons' turns no one else waits for and background jobs (file reading, graph building, research) while no helper is open, so they never get stuck."
  2. First observedv0.6.1

TDQS

A4/5.0
Behavior4/5

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

Goes beyond the annotations by disclosing the two possible outcomes — a work item, or status "idle" — which is the main behavioral fact an agent needs. It does not say whether a returned item is consumed/removed from the queue, and readOnlyHint=false hints at side effects the description never explains.

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

Conciseness5/5

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

Two sentences, front-loaded with the action and the return contract, with the retry instruction last. No wasted wording.

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?

No output schema exists, so the description carries the burden of explaining returns — which it does via the work-item/idle distinction. Missing is the fate of a returned item and any error behavior when the wait is interrupted.

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

Parameters3/5

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

Schema coverage is 100% and the per-parameter descriptions (helper role, lesson stickiness, full_context, timeout limits) are already thorough, so the description correctly does not duplicate them. It adds no parameter meaning beyond the schema, which is the expected baseline here.

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 ("wait for the next request from godspeed") and enumerates the work kinds it can return (lesson turn, Talk message, background job, knowledge-graph run), so an agent knows exactly what the tool yields. It never mentions the sibling read_work, so the one plausible confusion (poll vs. read) is not resolved by name.

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 actionable loop guidance: "then call again" after an idle status, which is the key usage instruction for a long-poll tool. It does not state when to prefer read_work or when not to use this at all, so an exclusion clause is missing.

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