voicehook

Wait for the next turn

next

Read-only

Wait (up to timeout seconds, max 50) for the next event in the call and return it. Event type: user (text = what the person said; after a pause also missed = earlier turns, oldest first, and away_s), revise (queued says were replaced; reason user_stop = the person said stop; reason stale + stale:true = your says waited over 60 s unspoken and were dropped (items = seq + text): do not repeat them, if still relevant say ONE short current summary), status_request (the person asked what the agent is doing), decision (answer to a decide question: id, number, verdict yes|no|option|other, option, text, by, answered_by, answered_via, answered_by_label), helper_decision (the human answered a helper session's question: from, label, id, number, question, verdict, option, text, by, answered_by, answered_via, answered_by_label; a routing hint, never speak or answer it: send it to that session so it continues), question_check (a status or activity line of this agent reads like a question to the person: id, quote, wait_s, text; answered by decide with the question, or by decide with no_question = id; without either, after wait_s the server puts it on the Decision Board itself, marked as detected automatically, answered only by a human), timeout (nothing happened; reconnect true = server restart), human_left / human_rejoined (the person dropped out / is back; greeted true = the join greeting was just spoken), voicebot_left / voicebot_back (the voicebot dropped out, e.g. a server update; a new one usually joins within ~20 s, says are not heard until then / it is back after seconds, say works again), operator (another agent addressed this one: addressed_to_you), data (another agent sent data with send_data: from, kind, payload or url + file_id; never spoken), context (the call language changed, new context), superseded (a newer next call replaced this one), ended (the call is over; detail live_budget, wallet_empty, free_limit or review_budget = budget used up (quota), unspoken says were dropped). Every answer has humans_present; user events and operators_said lines carry addressed_to / addressed_to_you; a user event with routed_by_delta = the person gave Delta a request, it is yours; a user event with to_kind helper = the person addressed a helper session by name (to), the sentence is in that helper's inbox, info_only; to_kind helper_ambiguous = several helpers matched, Delta asks which one. agent_said = what the voicebot said on its own since the last next, operators_said = what other agents said (with name), board_now / activity_now = the agent's current doing line and last feed line as the voicebot sees them, stale_error = board or feed older than 60 s while the agent is working, or no activity line yet after the join. Errors: 404 = unknown session (after leave); 5xx, 503 or a network error leave the session valid. Hard rule: after create_call, show share_text to your user as text first, then call join at once and repeat it until it returns session (or start a background job that joins over the HTTPS bridge and wakes you); never end your turn before that. Then keep calling next in a loop.

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": {
      "session": "<session>"
    },
    "name": "next"
  }
}

Input Schema

Name	Required	Description	Default
`session`	Yes	The `session` value returned by join.
`timeout`	No	Seconds to wait, max 50.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 17, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Goes well past the annotations (readOnly, openWorld, non-idempotent, non-destructive), which only say this is a safe poll. It explains the 50 s cap, that timeout is a normal no-event result, that `reconnect: true` means a server restart, that `superseded` means a newer next call replaced this one, that `ended` carries budget/limit detail codes, and that 404 means the session is gone while 5xx/503/network errors leave it valid.

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?

The purpose and the hard join rule are correctly front-loaded, but the body is one enormous run-on sentence of nested parentheticals enumerating every event field. Much of that enumeration duplicates the output schema and forces the reader to parse a wall of text to find the two or three events that change behavior.

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 long-poll loop tool with this much branching behavior, nothing essential is missing: call sequencing, error recovery, stale/revise handling, decision routing, and the meaning of the less common events are all covered. With an output schema present, the field-level enumeration is arguably redundant but not a gap.

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 `session` and `timeout` are already documented, but the description adds the consequence of the timeout value — that elapsed time yields a `timeout` event with `reconnect: true` on server restart — which the schema does not express. The max-50 cap is repeated from the schema, adding no new information.

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?

Opens with a precise verb+resource+scope: 'Wait (up to `timeout` seconds, max 50) for the next event in the call and return it,' and the exhaustive event enumeration leaves no doubt what comes back. It never names `helper_next` as the alternative for helper sessions, so the sibling distinction is only implied by references to 'this one' vs 'another agent'.

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?

Strong operational guidance: 'keep calling next in a loop,' the hard rule to show share_text then join before any turn ends, the instruction to route helper_decision to that session and never answer it, and to answer question_check via decide. What's missing is an explicit exclusion pointing an agent at `helper_next`/`helper_status` when it is driving a helper rather than its own call.

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

All voicehook tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.