Skip to main content
Glama
Sign In

voicehook

by io.github.voicehook-ai
OverviewDiscussionsAdmin

Ask the human to decide

decide
Destructive

Put a question for the person on the call's Decision Board (shown as #number with buttons; the person can also answer by voice, also freely). Meant for every question the person decides: yes/no, A/B, an approval, picking a value. A question only spoken via say leaves no button and no decision event. Without options it is a yes/no question (buttons Yes/No); options: 2 to 3, max 40 characters each, recommend = index of the recommended option. question: max 160 characters. Longer or more: 422, never cut. Returns id and number. The answer arrives later as a next event {type: decision, id, number, verdict: yes|no|option|other|unclear, option?, text? (their own answer, or for unclear the request to ask it again more simply), by (name), answered_by (who set it: owner|guest|delta_voice|helper|agent), answered_via (click|voice|api), answered_by_label (helper/agent label), answered_role?}. context: the background the person opens with the arrow next to the question on the card and Delta uses to explain it, only what the reader needs, nothing internal, one short line per part (Was / Warum / Bei Ja / Bei Nein, or What / Why / If yes / If no; lines starting with '- ' show as bullet points); faq: the 3 likely follow-up questions with prepared answers, shown below it as questions and answers. Without context and faq the card shows no arrow; without context and 3 faq the result carries warnings (no error). Change an open one with id plus new fields, remove it with id and delete true. no_question = id of a question_check event, alone: confirms that line was no question to the person. Decisions marked auto (detected automatically) are answered only by a human; changing or deleting them gives 403. card_type done = completion report instead of a question: title (whole sentence, max 160), summary (max 600), evidence [{label, url?}] (max 5, http(s) only), live (bool), ask (optional follow-up question); no question/options/recommend/context/faq (422). The server shows the single button Seen; it never counts as an open decision. Same sender and same title while unseen updates that card. When the person marks it, next gets {type: decision, card_type: done, id, number, verdict: seen, title, text? (answer to ask), by, answered_by, answered_via, answered_by_label}.

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

Input Schema

NameRequiredDescriptionDefault
idNoId of an open decision to change or delete.
askNocard_type done: optional follow-up question (one sentence ending with ?), answered in a text field next to Seen.
faqNoUp to 3 likely follow-up questions with prepared answers [{q, a}] (max 200 chars each), hidden, for the voicebot. Without context and 3 faq the result carries `warnings`.
goalNoOptional goal of this entry: number or title of a goal of the account (0 or empty = no goal). Unknown goals are ignored. Without it the entry inherits the goal of your last status (helpers: no inheriting).
liveNocard_type done: true = it is live (marked on the card).
titleNocard_type done: what is finished, one whole sentence, max 160 chars, no bare numbers.
ttl_sNoOptional: seconds until this card is hidden from the board if it is still open (or answered). Omit it and the card stays until it is answered or your session ends; never set a default.
deleteNotrue = remove the decision `id`.
contextNoBackground (max 1500 chars) the person opens with the arrow next to the question; Delta reads its first sentences aloud with the card and explains from it, so write it for the ear: an example, one key number, no lists. Only reader-relevant, one line per part: Was / Warum / Bei Ja / Bei Nein.
optionsNoOptional: 2 to 3 answer options, max 40 characters each; leave out for a yes/no question.
sessionYesThe `session` value returned by join.
summaryNocard_type done: short report, max 600 chars.
evidenceNocard_type done: up to 5 proofs [{label, url?}], url only http(s).
questionNoThe question, max 160 chars (required when creating).
card_typeNodecision (default) or done: a completion report ('work finished') with title, summary, evidence, live, ask instead of question/options; the person only marks it Seen, no decision.
recommendNoIndex (0-based) of your recommended option.
no_questionNoId of a question_check event: confirms the line was no question to the person (pass it alone).

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / goal
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional goal of this entry: number or title of a goal of the account (0 or empty = no goal). Unknown goals are ignored. Without it the entry inherits the goal of your last status (helpers: no inheriting).",
+  "title": "Goal"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / context / description
      Previous value: -"Background (max 1500 chars) the person opens with the arrow next to the question; Delta explains from it. Only reader-relevant, one line per part: Was / Warum / Bei Ja / Bei Nein."New value: +"Background (max 1500 chars) the person opens with the arrow next to the question; Delta reads its first sentences aloud with the card and explains from it, so write it for the ear: an example, one key number, no lists. Only reader-relevant, one line per part: Was / Warum / Bei Ja / Bei Nein."
  3. Changed1 schema field changed
    • addedInput schema / properties / ttl_s
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional: seconds until this card is hidden from the board if it is still open (or answered). Omit it and the card stays until it is answered or your session ends; never set a default.",
+  "title": "Ttl S"
+}
  4. Changed7 schema fields changed
    • addedInput schema / $defs / EvidenceItem
      Added value: +{
+  "properties": {
+    "label": {
+      "description": "What it proves, max 80 chars (e.g. 'All 412 tests green').",
+      "title": "Label",
+      "type": "string"
+    },
+    "url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Optional http(s) link (PR, CI run, live page).",
+      "title": "Url"
+    }
+  },
+  "required": [
+    "label"
+  ],
+  "title": "EvidenceItem",
+  "type": "object"
+}
    • addedInput schema / properties / ask
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "card_type done: optional follow-up question (one sentence ending with ?), answered in a text field next to Seen.",
+  "title": "Ask"
+}
    • addedInput schema / properties / card_type
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "decision (default) or done: a completion report ('work finished') with title, summary, evidence, live, ask instead of question/options; the person only marks it Seen, no decision.",
+  "title": "Card Type"
+}
    • addedInput schema / properties / evidence
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "$ref": "#/$defs/EvidenceItem"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "card_type done: up to 5 proofs [{label, url?}], url only http(s).",
+  "title": "Evidence"
+}
    • addedInput schema / properties / live
      Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "card_type done: true = it is live (marked on the card).",
+  "title": "Live"
+}
    • addedInput schema / properties / summary
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "card_type done: short report, max 600 chars.",
+  "title": "Summary"
+}
    • addedInput schema / properties / title
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "card_type done: what is finished, one whole sentence, max 160 chars, no bare numbers.",
+  "title": "Title"
+}
  5. Changed1 schema field changed
    • changedInput schema / properties / context / description
      Previous value: -"Background for Delta only (max 1500 chars, not shown on the card): 2-4 plain sentences: what, why, yes ->, no ->."New value: +"Background (max 1500 chars) the person opens with the arrow next to the question; Delta explains from it. Only reader-relevant, one line per part: Was / Warum / Bei Ja / Bei Nein."
  6. Changed1 schema field changed
    • addedInput schema / properties / no_question
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Id of a question_check event: confirms the line was no question to the person (pass it alone).",
+  "title": "No Question"
+}
  7. Changed2 schema fields changed
    • addedInput schema / $defs
      Added value: +{
+  "FaqPair": {
+    "properties": {
+      "a": {
+        "description": "The prepared answer, max 200 chars.",
+        "title": "A",
+        "type": "string"
+      },
+      "q": {
+        "description": "A likely follow-up question of the person, max 200 chars.",
+        "title": "Q",
+        "type": "string"
+      }
+    },
+    "required": [
+      "q",
+      "a"
+    ],
+    "title": "FaqPair",
+    "type": "object"
+  }
+}
    • addedInput schema / properties / faq
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "$ref": "#/$defs/FaqPair"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Up to 3 likely follow-up questions with prepared answers [{q, a}] (max 200 chars each), hidden, for the voicebot. Without context and 3 faq the result carries `warnings`.",
+  "title": "Faq"
+}
  8. Changed1 schema field changed
    • addedInput schema / properties / context
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Background for Delta only (max 1500 chars, not shown on the card): 2-4 plain sentences: what, why, yes ->, no ->.",
+  "title": "Context"
+}
  9. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Beyond the annotations (which already declare a write with destructiveHint=true), the description discloses the error paths (422 for over-long questions or invalid done fields, 403 for auto-detected decisions, `warnings` rather than an error when context/faq are thin), the card lifetime rules, and that the answer arrives asynchronously as a `next` event with a full verdict vocabulary. One nuance conflicts with the schema, however: the description says faq is 'shown below it as questions and answers' while the schema calls it 'hidden, for the voicebot'.

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 core purpose and the say-comparison are front-loaded, which is right, but the body is one dense run-on block of semicolon-joined clauses with no headings or bullets, and it spends a long stretch enumerating the full `next` event payload that structured output already covers. It is information-rich but would be markedly easier to scan if split into Create / Edit / Done / Response sections.

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 17-parameter tool with two card modes, an async answer channel, and several documented error codes, nothing an agent needs to call it correctly is missing: limits, required-vs-optional behavior, the edit/delete path, and the reply event shape are all present. The presence of an output schema makes the verbose return-value section redundant rather than necessary, but it does not leave gaps.

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 nonetheless adds real meaning for a few fields, e.g. that omitting options yields Yes/No buttons, that context lines starting with '- ' render as bullets, and that no_question must be passed alone. Several limits (2-3 options, 40 chars, 0-based recommend, 160 chars) restate the schema rather than extend it, which caps this at 4.

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 opens with a concrete verb and resource ('Put a question for the person on the call's Decision Board') and immediately names the sibling it is not: a question 'spoken via say leaves no button and no decision event.' It also distinguishes the card_type=done variant ('completion report instead of a question'), so an agent can separate three modes without opening a 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?

It states the intended scope explicitly ('Meant for every question the person decides: yes/no, A/B, an approval, picking a value') and gives the exclusion that matters (use say if you only want speech, because it produces no decision event). It also routes the two other modes: id plus new fields to change, id plus delete true to remove, and card_type done for finished work.

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