Skip to main content
Glama

Ask User a Question; May Call or Ring Their Phone If Unanswered

ask_user
Destructive

Ask for an unresolved decision or missing input. Prefer this over an in-app question when the user requests Pushary or mobile contact, is away, or work is unattended. Use it when the user asks you to call, phone or ring them if you get stuck or blocked. Supports confirm, select and input. Delivery follows account policy. When the reply includes phoneCall, Pushary may phone the person who can answer if the question is still unanswered, and records their answer; without phoneCall no call is planned. Waits at most 48 seconds and may return at once. While the reply is pending and has no handoffAction, keep waiting with wait_for_answer and the same correlationId. A poll ending does not cancel the question. Returns state, answer, delivery and handoff fields; answerUrl is optional. Sends a real question; it does not authorize other actions.

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": {
      "question": "<question>"
    },
    "name": "ask_user"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNoMACHINE-POPULATED. The working directory a hook resolved the rule for toolPath against, so a relative path rule resolves the same way here. Any other value is ignored. If you are a model deciding to call this tool, omit this field.
envNoSet to "test" from a test suite. The question is stored and returned as pending, and nothing is delivered to a phone, browser or Slack. The X-Pushary-Env: test header does the same for every call on the connection.
tagsNoDeliver only to subscribers that have any of these tags.
typeNoQuestion type: confirm renders yes/no buttons, select renders the options list, input renders a free-text field.confirm
waitNotrue (default) blocks until the user answers or the timeout fires. Set false to return immediately with a pending correlationId and poll it yourself via wait_for_answer.
actionNoThe concrete operation about to happen, one line. Shown as the Action line. Cut to 500 chars.
intentNoThe user's stated task (from their last prompt), one line. Shown as the Intent line so the user can see why the agent stopped. Cut to 500 chars.
blockerNoThe single gating reason the agent stopped, one line. Shown as the Blocker line. Cut to 500 chars.
contextNoOne or two sentences about what the agent is working on, shown above the question so the user can decide without opening the terminal.
optionsNoThe 2 to 6 choices for a select question. Required when type is "select", ignored otherwise. The answered value is the chosen option string, or the text the person typed instead when allowOther is true.
repoKeyNoStable repository identity for the working directory, e.g. "github.com/acme/api". Lets an approval routing rule scoped to one repository avoid governing another. Optional; omit it and only workspace-wide routing rules apply.
questionYesThe complete question, up to 8000 characters. Preserve every point. Notifications show a short preview; the answer interface shows the full question.
toolNameNoThe tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it.
toolPathNoMACHINE-POPULATED. Exact absolute path of the file a file tool call writes, as the hook matched its rule on. Any other value is ignored. Models must omit it.
agentNameNoName of the agent asking, format "{Agent} - {project}" (e.g. "Claude Code - myproject"). Shown in the notification title so the user knows which session needs them. Falls back to the MCP client name if omitted. Cut to 100 chars.
machineIdNoStable machine id of the asking agent, so two machines never collapse into one session.
questionsNoONE question, in the richer Claude-compatible shape: a header, per-option descriptions, multiSelect, and an optional write-in. Exactly one keeps already-installed clients answerable; asking several means several calls. Runtime-populated; ordinary callers should omit it and use question/type/options.
requestIdNoMACHINE-POPULATED. The CALLER's own identifier for one logical invocation, used only when the runtime supplies no toolUseId. Mint it once, outside your retry loop, and send the same value on every attempt, so three retries of one ask become one decision. Do NOT derive it from the question text or reuse it across two deliberate asks: both collapse a real second question into the first one's answer. If you are a model deciding to call this tool, omit this field.
scopePathNoSet ONLY when this approval exists because the path falls outside the scope the user ratified via propose_scope. Approving then widens the run scope to include this exact path, so the user is not asked again for the same area.
sessionIdNoOpaque per-session id of the asking agent, so parallel sessions are attributed separately.
timeoutMsNoHow long this call blocks, in milliseconds (up to 55000 is accepted; one call blocks at most 48 seconds). Defaults to the site policy timeout. Ordinary questions stay open until answered or cancelled; through a connector they close 10 minutes after they are sent. A timeout ends this poll only; follow up with wait_for_answer.
toolUseIdNoMACHINE-POPULATED. The agent RUNTIME's own identifier for the tool call this approval gates, forwarded verbatim by a hook that received it. Do NOT invent, guess, derive, or reuse a value: two different questions sent under the same id collapse into one, and the second one never reaches a human. If you are a model deciding to call this tool, omit this field.
actionBodyNoThe diff (Edit/Write) or full command (Bash/apply_patch), secret-redacted and size-capped. Rendered as a collapsible detail block; never used as the push body.
allowOtherNoSelect only, without questions: true also lets the person type an answer of their own, which is then the answered value. Set it unless your options cover every answer you could act on; omit it only then.
toolTargetNoCompact target of the tool call (e.g. the command head "git push" for Bash, or a file extension like ".ts" for Edit/Write). Used to mine policy suggestions.
waitEndsAtNoMACHINE-POPULATED. When the agent hook stops waiting live and hands control back to the terminal. The question may remain answerable after this time. Ordinary callers should omit it.
callbackUrlNoWebhook URL that receives a POST with the answer when the user responds, signed with the X-Pushary-Signature header. Useful when the agent process may exit before the answer arrives.
externalIdsNoDeliver only to subscribers matching these external IDs.
pausedAwareNoMACHINE-POPULATED. true from a hook that ends a paused approval exactly as the same approval unanswered after its full wait. Any other value is ignored. If you are a model deciding to call this tool, omit this field.
placeholderNoHint text shown inside the free-text field for input questions
matchedRouteNoMACHINE-POPULATED. The approval routing rule the hook matched on the machine, so this approval reaches the person that rule names. If you are a model deciding to call this tool, omit this field.
questionOwnerNoMACHINE-POPULATED. Ownership supplied by the supported personal Codex bridge. Models must omit this field.
subscriberIdsNoDeliver only to these subscriber IDs. Omit all targeting fields to reach every connected device.
permissionModeNoMACHINE-POPULATED. The agent runtime's own permission or approval mode for the tool call this approval gates, recorded with the decision. Any other value is ignored. If you are a model deciding to call this tool, omit this field.
callFingerprintNoMACHINE-POPULATED. A hook's fingerprint of the exact tool call, so the same call made again after the hook stopped waiting rejoins this question instead of asking twice. Any other value is ignored. If you are a model deciding to call this tool, omit this field.
routingToolNameNoMACHINE-POPULATED. The tool call this approval is about, sent by a client whose agent applies its own grant, and used only to match approval routing rules when toolName is absent. It never offers an always-allow rule. Any other value is ignored. If you are a model deciding to call this tool, omit this field.
sessionToolAwareNoMACHINE-POPULATED. Set by a Pushary hook whose engine applies a session tool grant with its risky-command ceiling, so the grant is only offered where it takes effect. If you are a model deciding to call this tool, omit this field.
routingToolTargetNoMACHINE-POPULATED. The compact target that goes with routingToolName, used only to match approval routing rules. Any other value is ignored. If you are a model deciding to call this tool, omit this field.
agentPromptFollowsNoMACHINE-POPULATED. false from a hook whose agent runs nothing and shows no prompt of its own when this approval is refused, so the approval is stored without a push past the question cap instead of refused. If you are a model deciding to call this tool, omit this field.
localSurfaceAvailableNoMACHINE-POPULATED. false from a hook that cannot show its own approval prompt for this call, so the phone is asked every time and never spared for presence at the keyboard. Any other value is ignored. If you are a model deciding to call this tool, omit this field.

Output Schema

NameRequiredDescriptionDefault
envNoEchoed when the call was test traffic.
heldNoPresent when the question was stored but deliberately not delivered: test traffic, or a permission ask with no toolName and no sessionId.
hintNoWhat to do next, when there is a next step.
modeNoThe site delivery mode that stopped this call from waiting.
noteNoFree text the user added alongside their answer.
typeYesThe question type that was rendered.
valueNoThe user's answer: "yes" or "no" for confirm, the chosen option for select (or the text they typed instead, when the select was asked with allowOther), the typed text for input.
pausedNoTrue when nothing was sent because the last approvals in this session went unanswered. Withdraw the question, then end the call as it would end unanswered.
statusNoThe question state. Only pending is a live unanswered wait; cancelled, expired, missing, and unavailable must not be described as timeouts.
warningNoPresent only when no channel is connected, naming what the user has to connect.
answeredNoTrue once the user responded. Absent on the wait:false path, where nothing was awaited.
deliveryNoPer-channel reach for the push carrying this question.
overflowNoTrue when the question was stored past the push cap: it is listed and answerable, but no push was sent for it. A wait on it is not a wait anyone was asked during, so a rule that approves on silence must not apply.
questionYesThe question exactly as the user saw it.
routedToNoWho the enforced route sends this decision to, for display, when requesterMayAnswer is false.
timedOutNoTrue when the initial wait ended while the question was still live. Poll once with wait_for_answer, then follow handoffAction when present, otherwise nextAction.
answerUrlNoOptional signed-in dashboard page where the user can answer this question.
noDevicesNoTrue when no phone, browser, or Slack channel could receive the question. Do not wait; follow handoffAction immediately.
phoneCallNoPresent only when Pushary plans to phone someone who can answer this question if it stays unanswered. Without it, no call is planned. The spoken answer arrives through wait_for_answer: while the reply is pending and has no handoffAction, keep waiting with the same correlationId.
nextActionNoBackward-compatible next step: keep waiting while pending or ask in the current client. Follow handoffAction first when present.
suppressedNoTrue when the PHONE push was deliberately held because a terminal on this machine is active, or, alongside paused, because nothing was sent at all. It says nothing about the notch, the dashboard or Slack, which are unaffected and may still be showing this question. A caller with no screen of its own should treat it as the terminal's to answer; a caller that can render the question itself should keep waiting unless paused is true.
waitEndsAtNoWhen the agent hook stops waiting live. On an idempotent replay this is the original question's deadline, which the hook must reuse.
typedAnswerNo
answerSourceNoRecorded answering surface, when known. Missing provenance is not proof of a phone answer; sandbox is simulated.
deliveryModeNoEffective delivery policy for this decision.
correlationIdYesId of the question that was created. Pass it to wait_for_answer to keep waiting, or to cancel_question to retract it.
handoffActionNoRace-safe directive for updated clients. Takes precedence over nextAction: cancel before asking in the current client, or stop the handoff.
policyTimeoutMsNoPolicy wait window in milliseconds. Callers must also honor their host deadline.
expiresInSecondsNoHow long the question stays answerable.
requesterMayAnswerNoFalse when a Team approval route that enforces who answers sends this decision to other people. Do not answer it in the current client or hand it to a local prompt: only the route's approvers can answer it.
phoneCallNotPlannedNoPresent only when the user who asked has phone calls set up and no call can be planned for this question. If they asked to be called, tell them why; never promise a call. Other reasons no call is planned are in hint only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / toolPath / description
      Previous value: -"MACHINE-POPULATED. Exact absolute path of the file a file tool call writes, as the hook matched its rule on. Models must omit it."New value: +"MACHINE-POPULATED. Exact absolute path of the file a file tool call writes, as the hook matched its rule on. Any other value is ignored. Models must omit it."
  2. Changed2 schema fields changed
    • removedInput schema / properties / toolPath / format
      Removed value: -"starts_with"
    • changedInput schema / properties / toolPath / pattern
      Previous value: -"^\\/.*"New value: +"^(?:\\/|[A-Za-z]:[\\\\/])"
  3. Changed4 schema fields changed
    • addedInput schema / properties / cwd
      Added value: +{
      +  "description": "MACHINE-POPULATED. The working directory a hook resolved the rule for toolPath against, so a relative path rule resolves the same way here. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 4096,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedInput schema / properties / toolPath / description
      Previous value: -"MACHINE-POPULATED. Exact absolute Write file_path from the runtime, for diagnostic correlation only. Models must omit it."New value: +"MACHINE-POPULATED. Exact absolute path of the file a file tool call writes, as the hook matched its rule on. Models must omit it."
    • addedOutput schema / properties / overflow
      Added value: +{
      +  "description": "True when the question was stored past the push cap: it is listed and answerable, but no push was sent for it. A wait on it is not a wait anyone was asked during, so a rule that approves on silence must not apply.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / typedAnswer
      Added value: +{
      +  "const": true,
      +  "type": "boolean"
      +}
  4. Changed1 schema field changed
    • changedInput schema / properties / allowOther / description
      Previous value: -"Select only, without questions: true also lets the person type an answer of their own, which is then the answered value. Omit it to accept only the options."New value: +"Select only, without questions: true also lets the person type an answer of their own, which is then the answered value. Set it unless your options cover every answer you could act on; omit it only then."
  5. Changed3 schema fields changed
    • addedInput schema / properties / allowOther
      Added value: +{
      +  "description": "Select only, without questions: true also lets the person type an answer of their own, which is then the answered value. Omit it to accept only the options.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / options / description
      Previous value: -"The 2 to 6 choices for a select question. Required when type is \"select\", ignored otherwise. The answered value is the chosen option string."New value: +"The 2 to 6 choices for a select question. Required when type is \"select\", ignored otherwise. The answered value is the chosen option string, or the text the person typed instead when allowOther is true."
    • changedOutput schema / properties / value / description
      Previous value: -"The user's answer: \"yes\" or \"no\" for confirm, the chosen option for select, the typed text for input."New value: +"The user's answer: \"yes\" or \"no\" for confirm, the chosen option for select (or the text they typed instead, when the select was asked with allowOther), the typed text for input."
  6. Changed2 schema fields changed
    • addedInput schema / properties / agentPromptFollows
      Added value: +{
      +  "description": "MACHINE-POPULATED. false from a hook whose agent runs nothing and shows no prompt of its own when this approval is refused, so the approval is stored without a push past the question cap instead of refused. If you are a model deciding to call this tool, omit this field.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / callFingerprint
      Added value: +{
      +  "description": "MACHINE-POPULATED. A hook's fingerprint of the exact tool call, so the same call made again after the hook stopped waiting rejoins this question instead of asking twice. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
  7. Changed3 schema fields changed
    • changedOutput schema / properties / phoneCallNotPlanned / description
      Previous value: -"Present only when the user who asked has phone calls set up but this question cannot be called. If they asked to be called, tell them why; never promise a call."New value: +"Present only when the user who asked has phone calls set up and no call can be planned for this question. If they asked to be called, tell them why; never promise a call. Other reasons no call is planned are in hint only."
    • changedOutput schema / properties / phoneCallNotPlanned / properties / reason / description
      Previous value: -"Why no call is planned for the user who asked."New value: +"Why no call is planned for the user who asked. Known values: agent_stops_waiting_first, outside_calling_hours, daily_call_limit_reached, no_call_minutes_left. Other values may be added; treat one you do not know as no call planned."
    • removedOutput schema / properties / phoneCallNotPlanned / properties / reason / enum
      Removed value: -[
      -  "agent_stops_waiting_first",
      -  "outside_calling_hours",
      -  "daily_call_limit_reached",
      -  "no_call_minutes_left"
      -]
  8. Changed3 schema fields changed
    • addedOutput schema / properties / phoneCall / properties / ringsAtLocal
      Added value: +{
      +  "description": "ringsAt in the requester's own time zone, such as \"16:03 on Friday 14 November (Europe/Berlin)\". Tell the user this time, not ringsAt. Absent when the callee is an approver.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / phoneCall / properties / status / description
      Previous value: -"planned: the call rings if the question is still unanswered. waiting_for_calling_hours: it is outside the requester's calling hours, and ringsAt is when they start."New value: +"planned: the call rings if the question is still unanswered. waiting_for_calling_hours: it is outside the requester's calling hours, and ringsAt and ringsAtLocal are when they start."
    • addedOutput schema / properties / phoneCallNotPlanned
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present only when the user who asked has phone calls set up but this question cannot be called. If they asked to be called, tell them why; never promise a call.",
      +  "properties": {
      +    "reason": {
      +      "description": "Why no call is planned for the user who asked.",
      +      "enum": [
      +        "agent_stops_waiting_first",
      +        "outside_calling_hours",
      +        "daily_call_limit_reached",
      +        "no_call_minutes_left"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "reason"
      +  ],
      +  "type": "object"
      +}
  9. Changed1 schema field changed
    • addedOutput schema / properties / phoneCall
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present only when Pushary plans to phone someone who can answer this question if it stays unanswered. Without it, no call is planned. The spoken answer arrives through wait_for_answer: while the reply is pending and has no handoffAction, keep waiting with the same correlationId.",
      +  "properties": {
      +    "callee": {
      +      "description": "requester: Pushary phones the user who asked. approver: it phones the person an approval route sends this question to, and says nothing about when.",
      +      "enum": [
      +        "requester",
      +        "approver"
      +      ],
      +      "type": "string"
      +    },
      +    "ringsAt": {
      +      "description": "When the call to the requester rings if nobody has answered by then. Absent when the callee is an approver.",
      +      "format": "date-time",
      +      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "planned: the call rings if the question is still unanswered. waiting_for_calling_hours: it is outside the requester's calling hours, and ringsAt is when they start.",
      +      "enum": [
      +        "planned",
      +        "waiting_for_calling_hours"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "callee",
      +    "status"
      +  ],
      +  "type": "object"
      +}
  10. Changed1 schema field changed
    • changedOutput schema / properties / answerSource / enum
      Previous value: -[
      -  "dashboard",
      -  "mobile_app",
      -  "mobile_background",
      -  "decide_page",
      -  "live_page",
      -  "answer_link",
      -  "inbox",
      -  "slack",
      -  "mac_app",
      -  "sandbox"
      -]New value: +[
      +  "dashboard",
      +  "mobile_app",
      +  "mobile_background",
      +  "decide_page",
      +  "live_page",
      +  "answer_link",
      +  "inbox",
      +  "slack",
      +  "mac_app",
      +  "voice_call",
      +  "sandbox"
      +]
  11. Changed1 schema field changed
    • addedInput schema / properties / matchedRoute
      Added value: +{
      +  "description": "MACHINE-POPULATED. The approval routing rule the hook matched on the machine, so this approval reaches the person that rule names. If you are a model deciding to call this tool, omit this field.",
      +  "properties": {
      +    "repoKey": {
      +      "maxLength": 200,
      +      "type": "string"
      +    },
      +    "toolPattern": {
      +      "maxLength": 4096,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "toolPattern"
      +  ],
      +  "type": "object"
      +}
  12. Changed2 schema fields changed
    • addedInput schema / properties / routingToolName
      Added value: +{
      +  "description": "MACHINE-POPULATED. The tool call this approval is about, sent by a client whose agent applies its own grant, and used only to match approval routing rules when toolName is absent. It never offers an always-allow rule. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 100,
      +  "type": "string"
      +}
    • addedInput schema / properties / routingToolTarget
      Added value: +{
      +  "description": "MACHINE-POPULATED. The compact target that goes with routingToolName, used only to match approval routing rules. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 80,
      +  "type": "string"
      +}
  13. Changed1 schema field changed
    • changedInput schema / properties / timeoutMs / description
      Previous value: -"How long this call blocks, in milliseconds (max 55000). Defaults to the site policy timeout. Ordinary questions stay open until answered or cancelled; through a connector they close 10 minutes after they are sent. A timeout ends this poll only; follow up with wait_for_answer."New value: +"How long this call blocks, in milliseconds (up to 55000 is accepted; one call blocks at most 48 seconds). Defaults to the site policy timeout. Ordinary questions stay open until answered or cancelled; through a connector they close 10 minutes after they are sent. A timeout ends this poll only; follow up with wait_for_answer."
  14. Changed2 schema fields changed
    • addedOutput schema / properties / requesterMayAnswer
      Added value: +{
      +  "description": "False when a Team approval route that enforces who answers sends this decision to other people. Do not answer it in the current client or hand it to a local prompt: only the route's approvers can answer it.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / routedTo
      Added value: +{
      +  "description": "Who the enforced route sends this decision to, for display, when requesterMayAnswer is false.",
      +  "type": "string"
      +}
  15. Changed2 schema fields changed
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +{}
    • changedOutput schema / properties / delivery / additionalProperties
      Previous value: -falseNew value: +{}
  16. Changed1 schema field changed
    • changedOutput schema / properties / suppressed / description
      Previous value: -"True when the PHONE push was deliberately held because a terminal on this machine is active. It says nothing about the notch, the dashboard or Slack, which are unaffected and may still be showing this question. A caller with no screen of its own should treat it as the terminal's to answer; a caller that can render the question itself should keep waiting."New value: +"True when the PHONE push was deliberately held because a terminal on this machine is active, or, alongside paused, because nothing was sent at all. It says nothing about the notch, the dashboard or Slack, which are unaffected and may still be showing this question. A caller with no screen of its own should treat it as the terminal's to answer; a caller that can render the question itself should keep waiting unless paused is true."
  17. Changed1 schema field changed
    • changedInput schema / properties / timeoutMs / description
      Previous value: -"How long this call blocks, in milliseconds (max 55000). Defaults to the site policy timeout. Ordinary questions stay open until answered or cancelled. A timeout ends this poll only; follow up with wait_for_answer."New value: +"How long this call blocks, in milliseconds (max 55000). Defaults to the site policy timeout. Ordinary questions stay open until answered or cancelled; through a connector they close 10 minutes after they are sent. A timeout ends this poll only; follow up with wait_for_answer."
  18. Changed1 schema field changed
    • addedInput schema / properties / questionOwner
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "MACHINE-POPULATED. Ownership supplied by the supported personal Codex bridge. Models must omit this field.",
      +  "properties": {},
      +  "type": "object"
      +}
  19. Changed1 schema field changed
    • changedInput schema / properties / timeoutMs / description
      Previous value: -"How long this call blocks, in milliseconds (max 55000). Defaults to the site policy timeout. The question stays open for 10 minutes regardless, so a timeout here is not a refusal; follow up with wait_for_answer."New value: +"How long this call blocks, in milliseconds (max 55000). Defaults to the site policy timeout. Ordinary questions stay open until answered or cancelled. A timeout ends this poll only; follow up with wait_for_answer."
  20. Changed4 schema fields changed
    • changedInput schema / properties / question / description
      Previous value: -"The question shown on the user's lock screen (500 chars; a longer one is cut). Phrase it so it is answerable at a glance; put background in context instead."New value: +"The complete question, up to 8000 characters. Preserve every point. Notifications show a short preview; the answer interface shows the full question."
    • addedInput schema / properties / question / maxLength
      Added value: +8000
    • changedInput schema / properties / questions / items / properties / question / maxLength
      Previous value: -500New value: +8000
    • changedOutput schema / properties / nextAction / description
      Previous value: -"Backward-compatible next step: poll once or ask in the current client. Follow handoffAction first when present."New value: +"Backward-compatible next step: keep waiting while pending or ask in the current client. Follow handoffAction first when present."
  21. Changed1 schema field changed
    • addedInput schema / properties / permissionMode
      Added value: +{
      +  "description": "MACHINE-POPULATED. The agent runtime's own permission or approval mode for the tool call this approval gates, recorded with the decision. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 64,
      +  "type": "string"
      +}
  22. Changed2 schema fields changed
    • addedInput schema / properties / pausedAware
      Added value: +{
      +  "description": "MACHINE-POPULATED. true from a hook that ends a paused approval exactly as the same approval unanswered after its full wait. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / paused
      Added value: +{
      +  "description": "True when nothing was sent because the last approvals in this session went unanswered. Withdraw the question, then end the call as it would end unanswered.",
      +  "type": "boolean"
      +}
  23. Changed1 schema field changed
    • addedInput schema / properties / localSurfaceAvailable
      Added value: +{
      +  "description": "MACHINE-POPULATED. false from a hook that cannot show its own approval prompt for this call, so the phone is asked every time and never spared for presence at the keyboard. Any other value is ignored. If you are a model deciding to call this tool, omit this field.",
      +  "type": "boolean"
      +}
  24. Changed1 schema field changed
    • changedOutput schema / properties / answerUrl / description
      Previous value: -"The signed-in dashboard page where this question is waiting. Print it when you tell the user you are waiting, so they can answer from a browser."New value: +"Optional signed-in dashboard page where the user can answer this question."
  25. Changed14 schema fields changed
    • changedInput schema / properties / action / description
      Previous value: -"The concrete operation about to happen, one line. Shown as the Action line."New value: +"The concrete operation about to happen, one line. Shown as the Action line. Cut to 500 chars."
    • removedInput schema / properties / action / maxLength
      Removed value: -500
    • addedInput schema / properties / action / minLength
      Added value: +0
    • changedInput schema / properties / agentName / description
      Previous value: -"Name of the agent asking, format \"{Agent} - {project}\" (e.g. \"Claude Code - myproject\"). Shown in the notification title so the user knows which session needs them. Falls back to the MCP client name if omitted."New value: +"Name of the agent asking, format \"{Agent} - {project}\" (e.g. \"Claude Code - myproject\"). Shown in the notification title so the user knows which session needs them. Falls back to the MCP client name if omitted. Cut to 100 chars."
    • removedInput schema / properties / agentName / maxLength
      Removed value: -100
    • addedInput schema / properties / agentName / minLength
      Added value: +0
    • changedInput schema / properties / blocker / description
      Previous value: -"The single gating reason the agent stopped, one line. Shown as the Blocker line."New value: +"The single gating reason the agent stopped, one line. Shown as the Blocker line. Cut to 500 chars."
    • removedInput schema / properties / blocker / maxLength
      Removed value: -500
    • addedInput schema / properties / blocker / minLength
      Added value: +0
    • changedInput schema / properties / intent / description
      Previous value: -"The user's stated task (from their last prompt), one line. Shown as the Intent line so the user can see why the agent stopped."New value: +"The user's stated task (from their last prompt), one line. Shown as the Intent line so the user can see why the agent stopped. Cut to 500 chars."
    • removedInput schema / properties / intent / maxLength
      Removed value: -500
    • addedInput schema / properties / intent / minLength
      Added value: +0
    • changedInput schema / properties / question / description
      Previous value: -"The question shown on the user's lock screen (max 500 chars). Phrase it so it is answerable at a glance; put background in context instead."New value: +"The question shown on the user's lock screen (500 chars; a longer one is cut). Phrase it so it is answerable at a glance; put background in context instead."
    • removedInput schema / properties / question / maxLength
      Removed value: -500
  26. Changed3 schema fields changed
    • addedInput schema / properties / toolPath / format
      Added value: +"starts_with"
    • changedInput schema / properties / waitEndsAt / pattern
      Previous value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"New value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
    • changedOutput schema / properties / waitEndsAt / pattern
      Previous value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"New value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
  27. Changed1 schema field changed
    • addedInput schema / properties / sessionToolAware
      Added value: +{
      +  "description": "MACHINE-POPULATED. Set by a Pushary hook whose engine applies a session tool grant with its risky-command ceiling, so the grant is only offered where it takes effect. If you are a model deciding to call this tool, omit this field.",
      +  "type": "boolean"
      +}
  28. Changed1 schema field changed
    • addedInput schema / properties / toolPath
      Added value: +{
      +  "description": "MACHINE-POPULATED. Exact absolute Write file_path from the runtime, for diagnostic correlation only. Models must omit it.",
      +  "maxLength": 4096,
      +  "pattern": "^\\/.*",
      +  "type": "string"
      +}
  29. 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"
      +}
  30. Changed2 schema fields changed
    • addedOutput schema / properties / deliveryMode
      Added value: +{
      +  "description": "Effective delivery policy for this decision.",
      +  "enum": [
      +    "push_first",
      +    "push_only",
      +    "notify_only",
      +    "terminal_only"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / policyTimeoutMs
      Added value: +{
      +  "description": "Policy wait window in milliseconds. Callers must also honor their host deadline.",
      +  "minimum": 0,
      +  "type": "number"
      +}
  31. Changed3 schema fields changed
    • addedInput schema / properties / env
      Added value: +{
      +  "description": "Set to \"test\" from a test suite. The question is stored and returned as pending, and nothing is delivered to a phone, browser or Slack. The X-Pushary-Env: test header does the same for every call on the connection.",
      +  "enum": [
      +    "test"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / env
      Added value: +{
      +  "description": "Echoed when the call was test traffic.",
      +  "enum": [
      +    "test"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / held
      Added value: +{
      +  "description": "Present when the question was stored but deliberately not delivered: test traffic, or a permission ask with no toolName and no sessionId.",
      +  "enum": [
      +    "test_traffic",
      +    "unattributed"
      +  ],
      +  "type": "string"
      +}
  32. Changed2 schema fields changed
    • addedInput schema / properties / waitEndsAt
      Added value: +{
      +  "description": "MACHINE-POPULATED. When the agent hook stops waiting live and hands control back to the terminal. The question may remain answerable after this time. Ordinary callers should omit it.",
      +  "format": "date-time",
      +  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      +  "type": "string"
      +}
    • addedOutput schema / properties / waitEndsAt
      Added value: +{
      +  "description": "When the agent hook stops waiting live. On an idempotent replay this is the original question's deadline, which the hook must reuse.",
      +  "format": "date-time",
      +  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      +  "type": "string"
      +}
  33. Changed1 schema field changed
    • changedOutput schema / properties / suppressed / description
      Previous value: -"True when the push was deliberately held because the user is at the keyboard and will see the terminal prompt instead."New value: +"True when the PHONE push was deliberately held because a terminal on this machine is active. It says nothing about the notch, the dashboard or Slack, which are unaffected and may still be showing this question. A caller with no screen of its own should treat it as the terminal's to answer; a caller that can render the question itself should keep waiting."
  34. Changed2 schema fields changed
    • changedInput schema / properties / questions / description
      Previous value: -"ONE question, in the richer Claude-compatible shape: a header, per-option descriptions, and multiSelect. Exactly one, because an answer carries no way to say which of several questions it belongs to, so a combined card cannot be answered from a phone, the decision page, or Slack. Asking several means several calls. Runtime-populated; ordinary callers should omit it and use question/type/options."New value: +"ONE question, in the richer Claude-compatible shape: a header, per-option descriptions, multiSelect, and an optional write-in. Exactly one keeps already-installed clients answerable; asking several means several calls. Runtime-populated; ordinary callers should omit it and use question/type/options."
    • addedInput schema / properties / questions / items / properties / allowOther
      Added value: +{
      +  "type": "boolean"
      +}
  35. Changed2 schema fields changed
    • changedInput schema / properties / questions / description
      Previous value: -"A bounded Claude-compatible question set rendered and submitted as one phone task. Runtime-populated; ordinary single-question callers should omit it."New value: +"ONE question, in the richer Claude-compatible shape: a header, per-option descriptions, and multiSelect. Exactly one, because an answer carries no way to say which of several questions it belongs to, so a combined card cannot be answered from a phone, the decision page, or Slack. Asking several means several calls. Runtime-populated; ordinary callers should omit it and use question/type/options."
    • changedInput schema / properties / questions / maxItems
      Previous value: -4New value: +1
  36. Changed6 schema fields changed
    • addedOutput schema / properties / handoffAction
      Added value: +{
      +  "description": "Race-safe directive for updated clients. Takes precedence over nextAction: cancel before asking in the current client, or stop the handoff.",
      +  "enum": [
      +    "cancel_then_ask_in_current_client",
      +    "stop"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / nextAction
      Added value: +{
      +  "description": "Backward-compatible next step: poll once or ask in the current client. Follow handoffAction first when present.",
      +  "enum": [
      +    "wait_for_answer",
      +    "ask_in_current_client"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / noDevices / description
      Previous value: -"True when no phone, browser, or Slack channel could receive the question at all. Stop waiting and fall back to the terminal."New value: +"True when no phone, browser, or Slack channel could receive the question. Do not wait; follow handoffAction immediately."
    • changedOutput schema / properties / status / description
      Previous value: -"Set only when no answer was awaited. pending: wait was false. notified: the site policy is notify_only. terminal: the user routed decisions to the terminal, so no push was sent."New value: +"The question state. Only pending is a live unanswered wait; cancelled, expired, missing, and unavailable must not be described as timeouts."
    • changedOutput schema / properties / status / enum
      Previous value: -[
      -  "pending",
      -  "notified",
      -  "terminal"
      -]New value: +[
      +  "answered",
      +  "pending",
      +  "cancelled",
      +  "expired",
      +  "missing",
      +  "unavailable",
      +  "notified",
      +  "terminal",
      +  "stopped"
      +]
    • changedOutput schema / properties / timedOut / description
      Previous value: -"True when this call returned before the user answered. Not a refusal: the question stays open for 10 minutes, so keep polling with wait_for_answer."New value: +"True when the initial wait ended while the question was still live. Poll once with wait_for_answer, then follow handoffAction when present, otherwise nextAction."
  37. Changed1 schema field changed
    • addedInput schema / properties / requestId
      Added value: +{
      +  "description": "MACHINE-POPULATED. The CALLER's own identifier for one logical invocation, used only when the runtime supplies no toolUseId. Mint it once, outside your retry loop, and send the same value on every attempt, so three retries of one ask become one decision. Do NOT derive it from the question text or reuse it across two deliberate asks: both collapse a real second question into the first one's answer. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 200,
      +  "type": "string"
      +}
  38. Changed1 schema field changed
    • addedInput schema / properties / questions
      Added value: +{
      +  "description": "A bounded Claude-compatible question set rendered and submitted as one phone task. Runtime-populated; ordinary single-question callers should omit it.",
      +  "items": {
      +    "properties": {
      +      "header": {
      +        "maxLength": 40,
      +        "type": "string"
      +      },
      +      "multiSelect": {
      +        "type": "boolean"
      +      },
      +      "options": {
      +        "items": {
      +          "properties": {
      +            "description": {
      +              "maxLength": 500,
      +              "type": "string"
      +            },
      +            "label": {
      +              "maxLength": 100,
      +              "minLength": 1,
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "label"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 4,
      +        "minItems": 2,
      +        "type": "array"
      +      },
      +      "question": {
      +        "maxLength": 500,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "question",
      +      "multiSelect",
      +      "options"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 4,
      +  "minItems": 1,
      +  "type": "array"
      +}
  39. Changed1 schema field changed
    • addedInput schema / properties / toolUseId
      Added value: +{
      +  "description": "MACHINE-POPULATED. The agent RUNTIME's own identifier for the tool call this approval gates, forwarded verbatim by a hook that received it. Do NOT invent, guess, derive, or reuse a value: two different questions sent under the same id collapse into one, and the second one never reaches a human. If you are a model deciding to call this tool, omit this field.",
      +  "maxLength": 200,
      +  "type": "string"
      +}
  40. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "answerUrl": {
      +      "description": "The signed-in dashboard page where this question is waiting. Print it when you tell the user you are waiting, so they can answer from a browser.",
      +      "type": "string"
      +    },
      +    "answered": {
      +      "description": "True once the user responded. Absent on the wait:false path, where nothing was awaited.",
      +      "type": "boolean"
      +    },
      +    "correlationId": {
      +      "description": "Id of the question that was created. Pass it to wait_for_answer to keep waiting, or to cancel_question to retract it.",
      +      "type": "string"
      +    },
      +    "delivery": {
      +      "additionalProperties": false,
      +      "description": "Per-channel reach for the push carrying this question.",
      +      "properties": {
      +        "mobile": {
      +          "description": "Phones the question reached.",
      +          "type": "number"
      +        },
      +        "pending": {
      +          "description": "True when delivery was still in flight when this returned, so the counts above are not final.",
      +          "type": "boolean"
      +        },
      +        "web": {
      +          "description": "Browsers the question reached.",
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "web",
      +        "mobile"
      +      ],
      +      "type": "object"
      +    },
      +    "expiresInSeconds": {
      +      "description": "How long the question stays answerable.",
      +      "type": "number"
      +    },
      +    "hint": {
      +      "description": "What to do next, when there is a next step.",
      +      "type": "string"
      +    },
      +    "mode": {
      +      "description": "The site delivery mode that stopped this call from waiting.",
      +      "enum": [
      +        "notify_only",
      +        "terminal_only"
      +      ],
      +      "type": "string"
      +    },
      +    "noDevices": {
      +      "description": "True when no phone, browser, or Slack channel could receive the question at all. Stop waiting and fall back to the terminal.",
      +      "type": "boolean"
      +    },
      +    "note": {
      +      "description": "Free text the user added alongside their answer.",
      +      "type": "string"
      +    },
      +    "question": {
      +      "description": "The question exactly as the user saw it.",
      +      "type": "string"
      +    },
      +    "status": {
      +      "description": "Set only when no answer was awaited. pending: wait was false. notified: the site policy is notify_only. terminal: the user routed decisions to the terminal, so no push was sent.",
      +      "enum": [
      +        "pending",
      +        "notified",
      +        "terminal"
      +      ],
      +      "type": "string"
      +    },
      +    "suppressed": {
      +      "description": "True when the push was deliberately held because the user is at the keyboard and will see the terminal prompt instead.",
      +      "type": "boolean"
      +    },
      +    "timedOut": {
      +      "description": "True when this call returned before the user answered. Not a refusal: the question stays open for 10 minutes, so keep polling with wait_for_answer.",
      +      "type": "boolean"
      +    },
      +    "type": {
      +      "description": "The question type that was rendered.",
      +      "enum": [
      +        "confirm",
      +        "select",
      +        "input"
      +      ],
      +      "type": "string"
      +    },
      +    "value": {
      +      "description": "The user's answer: \"yes\" or \"no\" for confirm, the chosen option for select, the typed text for input.",
      +      "type": "string"
      +    },
      +    "warning": {
      +      "description": "Present only when no channel is connected, naming what the user has to connect.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "correlationId",
      +    "question",
      +    "type"
      +  ],
      +  "type": "object"
      +}
  41. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations it discloses concrete behavior: a 48-second cap that may return at once, policy-driven delivery, the phoneCall-driven escalation where Pushary may phone the answerer and record their answer, and the fact that a poll ending does not cancel the question. It also names handoffAction as the signal for switching to wait_for_answer, which the annotations do not convey.

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?

Purpose is front-loaded and every sentence carries operational content, but the paragraph is dense and packs the async-wait, escalation, and return-value points into a single unbroken block. Slightly tighter grouping of the lifecycle rules would improve scanability without losing information.

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 40-parameter tool with an output schema, the description covers the essential decision path: when to call, how escalation works, how waiting continues, and what a poll ending means. The targeting and callback mechanics are left entirely to the schema, which is defensible given full schema coverage but leaves the targeting story unmentioned.

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 already 100%, so the baseline is 3. The description earns above that by explaining the question-type modes (confirm/select/input), the correlationId handoff mechanic, and the returned state/answer/delivery/handoff fields with optional answerUrl, but it says nothing about the many targeting or machine-populated parameters beyond the schema's own text.

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 opening sentence states a specific verb and resource: 'Ask for an unresolved decision or missing input.' Combined with the title, it makes clear this is a blocking human-question tool that can escalate to a phone call, which distinguishes it from in-app prompting and from siblings like wait_for_answer and send_notification.

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 selection criteria: prefer this over an in-app question when the user requests Pushary or mobile contact, is away, or work is unattended, and use it when the user asks to be called if the agent gets blocked. It also routes correctly during pending state by naming wait_for_answer with the same correlationId, and sets a boundary with 'it does not authorize other actions.'

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources