Skip to main content
Glama

Ask the human a yes/no or multiple-choice question (BLOCKS until they answer)

ask

Sends a yes/no or multiple-choice question to the user's phone via Blipr and blocks until they answer, returning approval or the selected option for human-in-the-loop decisions.

Instructions

Send a yes/no question (or, with options, a multiple-choice question) to the user's phone via Blipr and BLOCK until they tap an answer, then return it. This is a human-in-the-loop approval gate: use it before doing something consequential or irreversible (deleting prod data, force-pushing, spending money, sending an email) — anything where you'd otherwise ask 'should I proceed?'. The call does not return until the human answers or it times out. Returns { responded, approved, value, message_id, topic } — ALWAYS branch on approved: it is true ONLY when the human tapped Yes, and false on No, a timeout, or an error. Never treat a non-approval as a go-ahead. With options, the result has no approved: value is the option the human tapped, exactly as you passed it (trimmed). On timeout (or if your client cancels the call) the human may still answer within ~30 min — call check_reply with the returned message_id to resume rather than re-asking.

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": {
      "message": "<message>"
    },
    "name": "ask"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNoTags / emoji shortcodes, e.g. ["question"].
titleNoShort title, shown bold above the question.
topicNoTopic to publish to. Pass it explicitly — each project should use its own topic. When omitted, falls back to the project's `.blipr-topic` file, then the BLIPR_TOPIC env var.
messageYesThe question to ask the human.
optionsNoMakes this a multiple-choice question: 2 to 5 distinct, non-empty choices. Omit for a yes/no question.
markdownNoRender the body as Markdown (bold, italics, links, code). Off by default.
priorityNo1=min/silent … 5=critical. Defaults to 4 (high) since it needs an answer.
timeout_secondsNoHow long to block waiting for the answer before giving up. Defaults to 120s. Some MCP clients cancel a long tool call before this elapses; on timeout or cancel, use check_reply with the returned message_id (replies are retained ~30 min).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.7.0
    • changedInput schema / properties / message / description
      Previous value: -"The yes/no question to ask the human."New value: +"The question to ask the human."
    • addedInput schema / properties / options
      Added value: +{
      +  "description": "Makes this a multiple-choice question: 2 to 5 distinct, non-empty choices. Omit for a yes/no question.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 5,
      +  "minItems": 2,
      +  "type": "array"
      +}
  2. Changed3 schema fields changedv0.6.3
    • addedInput schema / properties / markdown
      Added value: +{
      +  "description": "Render the body as Markdown (bold, italics, links, code). Off by default.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / priority / description
      Previous value: -"1=min/silent … 5=critical. Defaults to 4 (time-sensitive) since it needs an answer."New value: +"1=min/silent … 5=critical. Defaults to 4 (high) since it needs an answer."
    • addedInput schema / properties / timeout_seconds / maximum
      Added value: +9007199254740991
  3. Changed1 schema field changedv0.4.0
    • changedInput schema / properties / topic / description
      Previous value: -"Topic to publish to. Defaults to the BLIPR_TOPIC env var."New value: +"Topic to publish to. Pass it explicitly — each project should use its own topic. When omitted, falls back to the project's `.blipr-topic` file, then the BLIPR_TOPIC env var."
  4. First observedv0.3.1

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so thoroughly: it discloses that the call blocks, that it times out, that the human may still answer within ~30 min after a timeout or client cancel, and that replies are retained. It also spells out the return shape and the critical branching rule that `approved` is true ONLY on an explicit Yes and false on No/timeout/error.

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?

Front-loaded with the core action and blocking behavior, then layered with usage, return contract, and timeout recovery. It is dense and long-ish, but nearly every sentence carries operational information; the return-shape sentence is slightly packed but not wasteful.

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?

There is no output schema, so the description must explain return values — and it does, enumerating { responded, approved, value, message_id, topic } and the mode-dependent absence of `approved`. For a blocking, side-effecting, human-facing tool with 8 parameters, the description covers the failure modes, recovery path, and result interpretation completely.

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, but the description adds real meaning beyond the schema: it explains that supplying `options` changes the result contract (no `approved`, `value` is the tapped option exactly as passed, trimmed) and that `timeout_seconds` interacts with client-side cancellation. It does not cover the remaining parameters (tags, title, topic, markdown, priority), which the schema handles adequately.

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?

States a specific verb and resource ('send a yes/no question ... to the user's phone via Blipr and BLOCK until they tap an answer') and immediately distinguishes the two modes (yes/no vs. multiple-choice via `options`). The blocking behavior is in the first sentence, so an agent knows exactly what this tool does before reading further.

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 when-to-use criteria with concrete examples ('deleting prod data, force-pushing, spending money, sending an email') and frames it as a human-in-the-loop approval gate. It also names the alternative path on timeout — call check_reply with the returned message_id rather than re-asking — which is exactly the routing guidance an agent needs.

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

Deploy Server

Other Tools