Skip to main content
Glama

Pushary

by com.pushary
OverviewDiscussionsAdmin

Wait for User Answer

wait_for_answer
Read-onlyIdempotent

Poll once for the user's answer to a previously created question: after ask_user times out, after ask_user with wait:false, or with a linkedCorrelationId from send_notification. Each call blocks until the answer arrives or timeoutMs expires (default 30 seconds, max 55). If a live question is still unanswered after this poll, handoffAction is "cancel_then_ask_in_current_client": cancel the phone question before asking in the current chat or client. If cancellation returns handoffAction "stop", stop. Otherwise, if cancellation returns false, poll once for 1 second and honor the answer that won the race. The response distinguishes pending, cancelled, expired, missing, and unavailable states; cancelled and unavailable mean stop rather than re-ask. nextAction retains only its original values for older clients. Returns { answered:true, status:"answered", value } once the user responds.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
timeoutMsNoHow long this one poll blocks, in milliseconds (default 30000, max 55000). Follow handoffAction when present, otherwise nextAction.
correlationIdYesThe correlationId from an earlier ask_user response, or the linkedCorrelationId from a send_notification with an embedded askQuestion

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
hintNoWhat to do next, when there is a next step.
noteNoFree text the user added alongside their answer.
valueNoThe user's answer: "yes" or "no" for confirm, the chosen option for select, the typed text for input. Present only when answered is true.
statusYesThe actual question state. Only pending is a live unanswered wait.
answeredYesTrue once the user responded. False means follow handoffAction when present, otherwise nextAction; do not guess that every unanswered state is a timeout.
nextActionNoBackward-compatible next step for older clients. Follow handoffAction first when present.
answerSourceNoRecorded answering surface, when known. Missing provenance is not proof of a phone answer; sandbox is simulated.
handoffActionNoRace-safe directive for updated clients. Takes precedence over nextAction.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / answerSource
      Added value: +{
+  "description": "Recorded answering surface, when known. Missing provenance is not proof of a phone answer; sandbox is simulated.",
+  "enum": [
+    "dashboard",
+    "mobile_app",
+    "mobile_background",
+    "decide_page",
+    "live_page",
+    "answer_link",
+    "inbox",
+    "slack",
+    "mac_app",
+    "sandbox"
+  ],
+  "type": "string"
+}
  2. Changed7 schema fields changed
    • changedInput schema / properties / timeoutMs / description
      Previous value: -"How long this call blocks, in milliseconds (default 30000, max 55000). Retry with the same correlationId to keep waiting; the question expires 10 minutes after it was asked."New value: +"How long this one poll blocks, in milliseconds (default 30000, max 55000). Follow handoffAction when present, otherwise nextAction."
    • changedOutput schema / properties / answered / description
      Previous value: -"True once the user responded. False means keep polling with the same correlationId, up to 3 times at timeoutMs 55000; it is a timeout on this call, not a refusal."New value: +"True once the user responded. False means follow handoffAction when present, otherwise nextAction; do not guess that every unanswered state is a timeout."
    • addedOutput schema / properties / handoffAction
      Added value: +{
+  "description": "Race-safe directive for updated clients. Takes precedence over nextAction.",
+  "enum": [
+    "cancel_then_ask_in_current_client",
+    "stop"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / hint
      Added value: +{
+  "description": "What to do next, when there is a next step.",
+  "type": "string"
+}
    • addedOutput schema / properties / nextAction
      Added value: +{
+  "description": "Backward-compatible next step for older clients. Follow handoffAction first when present.",
+  "enum": [
+    "wait_for_answer",
+    "ask_in_current_client"
+  ],
+  "type": "string"
+}
    • addedOutput schema / properties / status
      Added value: +{
+  "description": "The actual question state. Only pending is a live unanswered wait.",
+  "enum": [
+    "answered",
+    "pending",
+    "cancelled",
+    "expired",
+    "missing",
+    "unavailable"
+  ],
+  "type": "string"
+}
    • changedOutput schema / required
      Previous value: -[
-  "answered"
-]New value: +[
+  "answered",
+  "status"
+]
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "answered": {
+      "description": "True once the user responded. False means keep polling with the same correlationId, up to 3 times at timeoutMs 55000; it is a timeout on this call, not a refusal.",
+      "type": "boolean"
+    },
+    "note": {
+      "description": "Free text the user added alongside their answer.",
+      "type": "string"
+    },
+    "value": {
+      "description": "The user's answer: \"yes\" or \"no\" for confirm, the chosen option for select, the typed text for input. Present only when answered is true.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "answered"
+  ],
+  "type": "object"
+}
  4. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Even with readOnlyHint, idempotentHint, and destructiveHint already present, the description adds crucial behavioral detail: the call blocks until an answer or timeout (default 30s, max 55s), response states include pending/cancelled/expired/missing/unavailable, and cancelled/unavailable mean stop rather than re-ask. It also explains the cancellation race and the handoffAction behavior, which are not derivable from annotations or schema.

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 description is dense and front-loaded with the purpose, but it becomes a long run-on with multiple conditional branches packed into single sentences. The final 'Returns { answered:true, status:"answered", value }' sentence is redundant given the output schema exists. The structure is not badly organized, but the flow would be clearer with bullets or shorter sentences.

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?

Given the tool's complexity, the description covers the critical operational scenarios: when to poll, blocking/timeout behavior, cancellation handoff, response states, and stop-vs-re-ask semantics. With an output schema present, the lack of a full return-value spec is acceptable. Minor gaps remain around the ambiguous 'nextAction retains only its original values for older clients' statement, but overall the description is comprehensive enough for an agent to act correctly.

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 nevertheless adds meaning beyond the schema by explaining the consequences of timeoutMs expiring: it triggers cancellation logic, may return handoffAction, and can lead to a follow-up 1-second poll. It also clarifies the correlationId source and the 'previously created question' relationship, reinforcing the schema's parameter descriptions without merely repeating them.

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 resource: 'Poll once for the user's answer to a previously created question.' It distinguishes this tool from siblings by specifying when it applies: after ask_user times out, after ask_user with wait:false, or with a linkedCorrelationId from send_notification. This clearly separates it from ask_user and cancel_question.

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 explicitly states the three triggering scenarios for using this tool and gives concrete instructions for the cancellation/handoff flow. The description tells the agent exactly when to poll and how to follow handoffAction, including the 'stop' case and the fallback 1-second poll after cancellation. This is actionable usage guidance beyond what annotations or schema provide.

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

All Pushary 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