Skip to main content
Glama

ask_human

Posts a blocking question to a workspace person, arms the human gate, records your wait, and wakes you when answered.

Instructions

End your turn with a question only a person can answer: posts it as a Blocking question to that person, which arms the card's human gate and notifies them, records your wait on the answer and releases your checkout; you are woken when the gate is lifted. Refused, with nothing posted, when to is not a person of the workspace or the previous question already has an answer (name what is new in supersedes). A question to an agent is ask_agent.

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": {
      "task_id": "<task_id>",
      "to": "<to>",
      "question": "<question>"
    },
    "name": "ask_human"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesThe person's username, e.g. alex; an @ prefix is not needed.
softNotrue: the gate may be released by the default-on-timeout sweep. Default false (hard).
task_idYesThe card the question is about (UUID or 6-12 hex short id).
turn_idNoOptional turn id within the session (max 200 chars), copied onto the outcome.
deadlineNoWhen the default applies: RFC3339 with Z or an offset, in the future.
questionYesThe question with the options you see, max 2000 chars.
session_idNoOptional runner session id (max 200 chars), copied onto the recorded outcome and wait.
supersedesNoWhat the previous, already answered, question did not cover; one line.
canonical_keyNoNames the question; an existing recorded decision under the same key refuses the ask.
recommended_defaultNoWhat you will do if nobody answers by the deadline; one line, max 500 chars.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.7

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare this is neither read-only nor destructive and is not idempotent; the description adds real context beyond them — it releases the caller's checkout, records a wait, notifies the person, and wakes the caller when the gate is lifted, plus the two refusal paths. However, it does not explain the soft/hard and deadline interaction or what the caller receives when the gate lifts, leaving the most consequential runtime behavior to the schema.

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?

The core action and its effect are front-loaded in the first clause, with refusal conditions and the alternative following in priority order. The sentences are dense and clause-heavy (semicolon chaining), which costs some readability but little is wasted.

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?

For a ten-parameter, ten-annotation-blocking tool with no output schema, the description covers the essential mechanics: blocking, notification, checkout release, wake-up, and refusal. It stops short of describing what the caller sees when the wait ends or how soft versus hard gating changes the outcome, which are the remaining gaps an agent might care about.

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%, so the baseline is 3. The description contributes a little extra meaning — that `to` must be a person of the workspace and that `supersedes` should name what is new — but the ten parameters are otherwise left to the schema's own descriptions.

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 specific verb and outcome: it posts a Blocking question to a person, arms the card's human gate, and ends the caller's turn until woken. It explicitly marks the boundary with ask_agent ("A question to an agent is ask_agent"), so an agent can distinguish the two without opening schemas.

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 condition for use (a question only a person can answer) and the refusal conditions (recipient is not a person of the workspace, or the prior question at that point already has an answer, in which case use supersedes). It names the alternative sibling for the agent-directed case.

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