Skip to main content
Glama
Sign In

voicehook

by io.github.voicehook-ai
OverviewDiscussionsAdmin

Join a voicehook call

join

Connect to a voicehook.ai voice call as the agent behind its voicebot. invite_url: the full invite link including ?invite= (from the person or from create_call). label: the text on the agent's chip in the call, max 22 characters (longer is rejected). model: the model id the agent runs on (internal, not shown). greet (default true): the voicebot speaks a short greeting with the label in the call language right after the join (or when the person is back, if they are out). Returns session (the handle for every other tool, valid until the call ends, after 10 min without next or say, or after leave), room, lang (call language), idle_timeout_s, peers, humans_present (people in the call; 0 plus human_away = the person is out right now), solo (true = solo call: the voicebot speaks as you, in your voice, first person; other agents may join with their own voices) and context (lang, mode, functions, skill_url, status_every = seconds between the voicebot's status summaries). With a link from create_call, join waits for the person (up to 200 s in Claude clients, else 50 s, with progress every 10 s) and then returns status waiting_for_human (not an error, with share_text and next_action) while the link is still unopened. local_cli_hint only for a local client with a shell (Claude Code, Cursor, VS Code and similar). Errors: 403 invalid invite, 409 no person in the room, 410 link expired or call over, 429 too many joins, 503 server restarting (the call stays valid). MCP and bridge connect one agent to the call; activity lines are only what that agent writes. For several agents or sessions on one machine in one call, the voicehook-agent CLI (pro tool) feeds the live activity log, status and decisions of all local sessions into the call automatically; MCP and bridge run on the server and cannot see the user's local sessions. 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": {
      "invite_url": "<invite_url>"
    },
    "name": "join"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoOld name of `label` (still accepted).
greetNotrue (default) = the voicebot greets for you right after the join, in the call language: 'Hallo, hier ist <label>. Worum geht es?' / 'Hi, this is <label>. What can I do for you?'.
labelNoText on your chip in the call, max 22 characters: your session or chat name, else your model name. Too long is rejected.
modelNoExact model id you run on (internal, not shown).unbekannt
quietNoAccepted for compatibility with the HTTPS bridge; no effect here.
voiceNoOptional Chirp3-HD voice for the agent in normal mode, short name (e.g. Puck) or full name; invalid values are ignored. In a one-agent call the voicebot speaks in this voice.
invite_urlYesInvite link https://voicehook.ai/r/<room>?invite=... (max 2048 chars)
data_channelNofalse (default): every user turn addressed to you wakes your `next`. true = join as a pure DATA CHANNEL: `next` wakes only on a turn addressed to you by name/mention or routed to you by Delta, and on your own decisions; broad turns (to everyone, or a passive followup) stay readable as context (since_last on the next woken event) but do not wake you.
status_everyNoOptional seconds between the voicebot's own status summaries of your board, activity and decisions (default 60; 0 = only when the person asks; 10..59 or whole minutes up to 3600). The person can change it in the call.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / data_channel
      Added value: +{
+  "default": false,
+  "description": "false (default): every user turn addressed to you wakes your `next`. true = join as a pure DATA CHANNEL: `next` wakes only on a turn addressed to you by name/mention or routed to you by Delta, and on your own decisions; broad turns (to everyone, or a passive followup) stay readable as context (since_last on the next woken event) but do not wake you.",
+  "title": "Data Channel",
+  "type": "boolean"
+}
  2. Changed1 schema field changed
    • addedInput schema / properties / status_every
      Added value: +{
+  "anyOf": [
+    {
+      "maximum": 3600,
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional seconds between the voicebot's own status summaries of your board, activity and decisions (default 60; 0 = only when the person asks; 10..59 or whole minutes up to 3600). The person can change it in the call.",
+  "title": "Status Every"
+}
  3. Changed1 schema field changed
    • addedInput schema / properties / voice
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 100,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional Chirp3-HD voice for the agent in normal mode, short name (e.g. Puck) or full name; invalid values are ignored. In a one-agent call the voicebot speaks in this voice.",
+  "title": "Voice"
+}
  4. First observed

TDQS

A4.7/5.0
Behavior5/5

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

The description discloses extensive behavior beyond annotations: session lifetime, idle timeout, waiting_for_human semantics, return fields, error codes, local_cli_hint behavior, and multi-agent limitations. This is well above the baseline needed for an open-world, non-destructive mutation-like join operation.

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 critical purpose is front-loaded, but the description is a dense wall of clauses mixing return values, errors, workflow rules, and multi-agent distinctions. Much is useful, but the structure makes 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.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, annotations, output schema, and nine parameters, the description is complete enough to call it correctly. It covers lifecycle, returns, errors, timing, and operational constraints.

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 schema already documents all parameters. The description nonetheless adds useful meaning for invite_url, label length rejection, greet timing, model visibility, and returned session fields, but it does not clarify every parameter such as quiet or data_channel beyond the schema.

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 states a specific verb and resource: connect to a voicehook.ai voice call as the agent behind its voicebot. It clearly distinguishes this from create_call and other sibling tools by explaining the invite flow and session handle.

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?

It gives explicit usage conditions, including the hard rule after create_call, when to repeat join, and how several-agent scenarios should use the CLI instead of MCP/bridge. Alternatives and timing are named directly.

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

All voicehook toolsInspect
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.

Resources