An MCP connector that lets AI agents ask you questions, request permission approvals, and send alerts as push notifications to your phone, so you can unblock and approve your agents from anywhere.
Scored across 5 tools
Each tool has a clearly distinct role: ask_user blocks for a new answer, wait_for_answer polls an existing question, cancel_question retires a pending one, send_notification is one-way, and propose_scope handles run-scope approval. Even the two question-related tools are cleanly separated by blocking versus polling semantics.
All tool names follow a consistent verb_noun snake_case pattern: ask_user, cancel_question, propose_scope, send_notification, wait_for_answer. The naming is predictable and makes the action and target of each tool immediately clear.
Five tools is well-scoped for a push-notification and user-decision server. Each tool covers a necessary part of the lifecycle without redundancy or bloat.
The surface covers the full question lifecycle: create/ask, poll, cancel, and one-way notification, plus a specialized scope-approval flow. There are no obvious dead ends for the server's stated purpose.
Ask the user a question as a push notification on their phone and block until they answer. Reach for this whenever you need the user's decision and they may be away from the current client: approving a risky or irreversible step (deleting files, force pushing, spending money, sending external messages), picking between implementation options, or supplying missing input. The user answers from the lock screen or a decision page; you do not need a separate wait_for_answer call because this tool waits by default. Three question types: "confirm" (yes/no), "select" (2 to 6 fixed choices), "input" (free text). A single call blocks for at most 55 seconds. If a live question times out, nextAction is "wait_for_answer": poll once with timeoutMs 55000. If that poll is also unanswered, 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. Cancelled, expired, and missing questions are reported as terminal states rather than as timeouts. Every response carries answerUrl, the signed-in dashboard page where this question is waiting. When you report that you are waiting, print that URL to the user so they can answer from a browser instead of hunting for it. Works from Claude Code, Codex, Cursor, Hermes, or any MCP client; no Claude subscription is required. SIDE EFFECT: sends a real push notification.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 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. | |
| tags | No | Deliver only to subscribers that have any of these tags. | |
| type | No | Question type: confirm renders yes/no buttons, select renders the options list, input renders a free-text field. | confirm |
| wait | No | true (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. | |
| action | No | The concrete operation about to happen, one line. Shown as the Action line. | |
| intent | No | 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. | |
| blocker | No | The single gating reason the agent stopped, one line. Shown as the Blocker line. | |
| context | No | One or two sentences about what the agent is working on, shown above the question so the user can decide without opening the terminal. | |
| options | No | The 2 to 6 choices for a select question. Required when type is "select", ignored otherwise. The answered value is the chosen option string. | |
| repoKey | No | Stable 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. | |
| question | Yes | 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. | |
| toolName | No | The tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it. | |
| toolPath | No | MACHINE-POPULATED. Exact absolute Write file_path from the runtime, for diagnostic correlation only. Models must omit it. | |
| agentName | No | 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. | |
| machineId | No | Stable machine id of the asking agent, so two machines never collapse into one session. | |
| questions | No | 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. | |
| requestId | No | 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. | |
| scopePath | No | Set 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. | |
| sessionId | No | Opaque per-session id of the asking agent, so parallel sessions are attributed separately. | |
| timeoutMs | No | 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. | |
| toolUseId | No | 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. | |
| actionBody | No | The 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. | |
| toolTarget | No | Compact 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. | |
| waitEndsAt | No | 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. | |
| callbackUrl | No | Webhook 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. | |
| externalIds | No | Deliver only to subscribers matching these external IDs. | |
| placeholder | No | Hint text shown inside the free-text field for input questions | |
| subscriberIds | No | Deliver only to these subscriber IDs. Omit all targeting fields to reach every connected device. |
| Name | Required | Description |
|---|---|---|
| env | No | Echoed when the call was test traffic. |
| held | No | Present when the question was stored but deliberately not delivered: test traffic, or a permission ask with no toolName and no sessionId. |
| hint | No | What to do next, when there is a next step. |
| mode | No | The site delivery mode that stopped this call from waiting. |
| note | No | Free text the user added alongside their answer. |
| type | Yes | The question type that was rendered. |
| value | No | The user's answer: "yes" or "no" for confirm, the chosen option for select, the typed text for input. |
| status | No | The question state. Only pending is a live unanswered wait; cancelled, expired, missing, and unavailable must not be described as timeouts. |
| warning | No | Present only when no channel is connected, naming what the user has to connect. |
| answered | No | True once the user responded. Absent on the wait:false path, where nothing was awaited. |
| delivery | No | Per-channel reach for the push carrying this question. |
| question | Yes | The question exactly as the user saw it. |
| timedOut | No | 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. |
| answerUrl | No | 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. |
| noDevices | No | True when no phone, browser, or Slack channel could receive the question. Do not wait; follow handoffAction immediately. |
| nextAction | No | Backward-compatible next step: poll once or ask in the current client. Follow handoffAction first when present. |
| suppressed | No | 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. |
| waitEndsAt | No | When the agent hook stops waiting live. On an idempotent replay this is the original question's deadline, which the hook must reuse. |
| answerSource | No | Recorded answering surface, when known. Missing provenance is not proof of a phone answer; sandbox is simulated. |
| deliveryMode | No | Effective delivery policy for this decision. |
| correlationId | Yes | Id of the question that was created. Pass it to wait_for_answer to keep waiting, or to cancel_question to retract it. |
| handoffAction | No | Race-safe directive for updated clients. Takes precedence over nextAction: cancel before asking in the current client, or stop the handoff. |
| policyTimeoutMs | No | Policy wait window in milliseconds. Callers must also honor their host deadline. |
| expiresInSeconds | No | How long the question stays answerable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already flag destructiveHint=true and idempotentHint=false, and the description goes further by disclosing the real side effect: 'SIDE EFFECT: sends a real push notification.' It details blocking up to 55 seconds, the distinction between timeouts and terminal states, the answerUrl in every response, and the recommendation to print that URL. This is rich behavioral context that complements the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and mixes essential purpose and usage with operational details (timeout/cancellation flow) and some non-essential content ('Works from Claude Code, Codex, Cursor, Hermes, or any MCP client; no Claude subscription is required'). It is front-loaded with the primary use case)Skip, but could be tightened to reduce noise. The core guidance is useful, but not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 28 parameters, a powerful output schema, and side effects, the description provides a complete orientation: purpose, when to use, side effect disclosure, blocking/timeout semantics, and explicit interaction with sibling tools (wait_for_answer, cancel_question). The agent can correctly invoke the tool and handle the response lifecycle without needing additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds some high-level meaning for the `type` and `wait` parameters (three question types, default blocking behavior), but does not enumerate or explain each of the 28 parameters. It neither compensates heavily nor falls short; it's adequate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise action: 'Ask the user a question as a push notification on their phone and block until they answer.' It names the resource (user question), mechanism (push notification), and blocking behavior. It also differentiates from sibling tools by explicitly saying no separate wait_for_answer call is needed and outlining when cancel_question applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the exact conditions for use: 'whenever you need the user's decision and they may be away from the current client,' with concrete examples (approving risky steps, picking options, supplying missing input). It also provides an explicit timeout/retry procedure that routes to wait_for_answer and cancel_question, giving clear guidance on which sibling to use next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retract a pending question so it can no longer be answered. Use this when a question became irrelevant before the user replied: the agent found the answer itself, the task was aborted, or a newer question supersedes it. Cancelling prevents a stale approval from arriving later and acting on work that has moved on. Only affects questions that are still pending; questions expire on their own 10 minutes after creation. Returns { cancelled: true } when a pending question was removed. False means it was already answered, expired, unknown, or unavailable; when status is unavailable, follow handoffAction and stop rather than opening another answer surface.
| Name | Required | Description | Default |
|---|---|---|---|
| handoff | No | True when you are cancelling because you are about to ask the same question in the current client. For the next minute the Pushary hook then lets your own question tool through instead of sending it back to the phone. Set automatically whenever a live question is cancelled. | |
| correlationId | Yes | The correlationId of the pending question to cancel, as returned by ask_user or send_notification |
| Name | Required | Description |
|---|---|---|
| hint | No | What to do when cancellation could not safely inspect the question. |
| status | No | Present when Pushary could not safely read or fence the question state. |
| cancelled | Yes | True when a still-pending question was removed. False when it was already terminal, missing, or unavailable; inspect status and handoffAction when present. |
| askHandoff | No | True when the session was marked as handing off to the current client, so the hook will not re-ask on the phone for the next minute. |
| correlationId | Yes | The question this result refers to, echoed back. |
| handoffAction | No | Stop rather than opening another answer surface when the question state is unavailable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description discloses meaningful behavioral details: cancellation prevents stale approvals, only pending questions are affected, questions self-expire, and the return value semantics for true versus false are fully described, including the special unavailable status with handoffAction guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds necessary context: action, use cases, rationale, scope limits, and return semantics. It is well-structured and front-loads the primary purpose before edge-case behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers the full lifecycle: when to cancel, what happens after cancellation, what return values mean, and how to handle the unavailable status. Nothing needed to invoke or interpret the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already fully documented in the input schema. The description adds no new parameter-level meaning beyond what the schema provides, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Retract a pending question so it can no longer be answered.' It immediately distinguishes itself from sibling tools like ask_user and wait_for_answer by focusing on cancellation of an already-issued question.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool — when the agent found the answer itself, the task was aborted, or a newer question supersedes it — and also states limits: only pending questions are affected, and questions expire after 10 minutes. This gives clear decision guidance without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose what this run will touch and block until the user ratifies it. Call ONCE at the start of a multi-step run, before doing work. The user sees the paths you intend to change, the areas you promise to leave alone, and your definition of done, and approves the whole thing in one tap. After that, editing a file outside the agreed scope stops being auto-approvable: it becomes a separate "wants to widen scope" question instead of a silent approval, so you are asked once about the boundary rather than repeatedly about each file. Use glob syntax ("src/", "docs/"). WHAT IS ENFORCED: only file paths, and only for tool calls that carry one (Edit, Write, MultiEdit). Shell commands, Read, web requests and every MCP tool carry no path, so a contract says nothing about them and they stay governed by the permission policy. A contract with no paths at all therefore gates NOTHING: use promises for a run that touches no files, and read the returned "enforces" rather than assuming ratified:true means something is being checked. A scope can only turn an automatic approval into a question; it never turns a question into an approval. Scope lives for this session only and is never inherited by another run. Returns { correlationId, ratified, answered, value, enforces, contract }. If the first wait times out, poll its correlationId once; a late phone yes ratifies the stored proposal. If that poll is also pending, cancel it before asking in the current chat whether to continue without an enforced scope. If cancellation loses a race, honor the phone answer instead. Never describe a client-only agreement as ratification. SIDE EFFECT: sends a real push notification.
| Name | Required | Description | Default |
|---|---|---|---|
| doneWhen | Yes | What "finished" means for this run, one or two lines. Carried for the human to judge against; never enforced automatically. | |
| promises | No | Boundaries that are not file paths: recipients, channels, spend limits, systems you will not open. For an agent whose work is not code (marketing, sales, support, operations), this is where the boundary goes. Shown to the user labelled "Promised, not checked" and recorded in the ledger, but NEVER enforced, because the gate judges a file path and these have none. Do not put these in allowedPaths. | |
| agentName | No | Name of the agent asking, format "{Agent} - {project}". | |
| machineId | No | Stable machine id, so two machines never collapse into one session. | |
| sessionId | Yes | Your per-session id, as your client reports it for THIS run. Required, and it is the key the gate reads the contract back by: a value that matches no live session still returns ratified:true and enforces nothing. Never invent one, and never reuse one from another run. | |
| timeoutMs | No | How long this call blocks, in milliseconds (max 55000). | |
| allowedPaths | No | Globs you intend to change, e.g. ["src/**", "docs/*.md"]. File paths only: a word that is not a path ("hubspot", "summer-campaign") matches no file and makes every edit read as out of scope. A bare directory is expanded for you, so "docs" also covers "docs/**". Omit or leave empty to propose no path restriction, which the user is told plainly. | |
| offLimitsPaths | No | Globs you promise not to touch, e.g. [".env*", "infra/**"]. These win wherever they overlap allowedPaths. A leading "**/" needs a directory before it, so "**/.env*" is expanded for you to also cover a root ".env". |
| Name | Required | Description |
|---|---|---|
| note | No | Present only when the scope is not in force, saying what to do instead of proceeding. |
| value | No | The raw answer behind ratified, "yes" or "no". |
| status | No | The underlying scope-question state. |
| answered | Yes | True when the user responded at all. Answered but not ratified means they declined, so ask what scope they want rather than proceeding. |
| contract | Yes | The scope as it is STORED and gated, echoed back so you and the server hold the same contract. Paths are the EXPANDED ones: a bare directory and a leading "**/" each gain the variant they would otherwise have missed, so this can contain more entries than you sent. The user was shown the paths you sent, because the added twin says the same thing to a reader; the expansion only changes what the matcher covers, never what it means. |
| enforces | Yes | What this contract CONTAINS that can be checked, not a promise about what the gate on this machine will do. An EMPTY array means nothing here is checked automatically: the contract is a recorded promise, and every action stays governed by the permission policy exactly as it was before. Never tell the user a boundary is enforced when this is empty. |
| hookSeen | No | Whether any agent hook has actually reported this sessionId. FALSE means the gate will look this contract up under a key that does not exist, so nothing will be checked no matter what ratified says: fix the session id rather than proceeding as if a scope were in force. ABSENT means the check could not run, which is not evidence either way. |
| ratified | Yes | True only on an explicit yes. The contract is in force for this session only when this is true; anything else means proceed as if no scope was agreed. |
| nextAction | No | Poll one live question once; otherwise ask in the current chat whether to continue without an enforced scope. |
| correlationId | Yes | Id of the scope question. Pass it to wait_for_answer once when the first wait times out. |
| handoffAction | No | Race-safe directive for updated clients. Takes precedence over nextAction. |
| enforcementNote | No | Present only when there is something true to say about the limits of this contract. Repeat it to the user rather than paraphrasing it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the push-notification side effect, blocking behavior, timeout/polling/cancellation races, session-only lifetime, and the 'enforces' flag meaning. It thoroughly explains what is and isn't enforced without contradicting the existing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every sentence carries essential operational detail and is logically structured: definition, usage, enforcement scope, edge cases, return value, and side effects. Front-loaded with the core directive and then expanding into the contractual nuances an agent must know.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with this complexity, the description covers all critical scenarios: polling, late ratification, cancellation races, no-path contracts, and clarifying that ratified:true doesn't imply enforcement. Combined with the rich output schema, nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even with 100% schema coverage, the description adds high-value parameter semantics: glob syntax expansion, directory auto-expansion, off-limits precedence, promises being never-enforced, doneWhen never auto-enforced, and sessionId matching behavior. These clarifications prevent misuse that raw schema would not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Propose what this run will touch and block until the user ratifies it.' It clearly distinguishes itself from sibling tools (ask_user, send_notification, etc.) by stating it is the gate-setting action for a multi-step run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call ONCE at the start of a multi-step run, before doing work' and gives detailed when-not-to-use guidance: use promises for file-less runs, note that shell/web/MCP calls are not covered, and a scope only turns auto-approvals into questions, never the reverse. This fully routes the agent to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a one-way push notification to the user's phone and browser. Nothing is awaited; use ask_user instead when you need an answer back. Reach for this when a long-running task finishes and the user asked to be told, when the agent hits an error it cannot resolve on its own, or for any "notify me when my agent needs me" moment while the user is away from the terminal. By default the notification reaches every device connected to the site; narrow delivery with subscriberIds, externalIds, or tags. The optional context object turns the tap-through into a rich detail page (summary, bullet details, changed files, error info, next steps), and context.askQuestion embeds a decision prompt on that page, returning a linkedCorrelationId you can poll with wait_for_answer. Returns per-channel delivery counts for web and mobile, plus a warning when zero devices are connected. Works from Claude Code, Codex, Cursor, Hermes, or any MCP client; no Claude subscription is required. SIDE EFFECT: delivers real notifications to real devices immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Set to "test" from a test suite. The notification is recorded in the activity feed and nothing is delivered to a phone or browser. The X-Pushary-Env: test header does the same for every call on the connection. | |
| url | No | URL opened when the user taps the notification. Ignored if context is provided, because a context detail page URL is generated automatically. | |
| body | Yes | Notification body text (max 500 chars). One or two sentences the user can act on without opening anything. | |
| tags | No | Deliver only to subscribers that have any of these tags. | |
| title | Yes | Notification title shown on the lock screen (max 100 chars). Lead with the outcome, e.g. "Build finished" or "Migration failed". | |
| context | No | Structured context rendered as a rich detail page when the user taps the notification. Strongly recommended for task_complete and error notifications so the user can act from their phone. | |
| iconUrl | No | URL of the notification icon image | |
| imageUrl | No | URL of a large image shown in the notification | |
| agentName | No | Name of the agent sending this notification, format "{Agent} - {project}" (e.g. "Claude Code - myproject"). Shown in the notification so the user knows which session is talking. Falls back to the MCP client name if omitted. | |
| machineId | No | Stable machine id of the sending agent, so two machines never collapse into one session. | |
| sessionId | No | Opaque per-session id of the sending agent, so parallel sessions are attributed separately in the activity feed. | |
| externalIds | No | Deliver only to subscribers matching these external IDs. | |
| subscriberIds | No | Deliver only to these subscriber IDs. Omit all targeting fields to reach every connected device. |
| Name | Required | Description |
|---|---|---|
| env | No | Echoed when the call was test traffic. |
| hint | No | What to do next, when there is a next step. |
| sent | No | Total devices reached, web plus mobile. Zero is a successful call that found nobody to deliver to, not an error. |
| warning | No | Present only when the notification reached zero devices, naming what the user has to connect. |
| delivery | No | Per-channel outcome. The two channels are independent with no cross-fallback, so each reports its own result. |
| linkedCorrelationId | No | Present only when context.askQuestion embedded a decision prompt. Pass it to wait_for_answer to collect the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the side effect: 'SIDE EFFECT: delivers real notifications to real devices immediately.' It also explains that nothing is awaited, narrows delivery options, warns about zero connected devices, and notes that context.askQuestion returns a linkedCorrelationId that can be polled. The annotations already say destructiveHint=true, but the description goes far beyond that with concrete behavioral details. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is packed with valuable information, but it's a bit long and could be more tightly organized. The opening sentence, the SIDE EFFECT warning, and the when-to-use guidance are all front-loaded. The middle section about targeting and context is dense but deserves its place. It could be slightly trimmed, but it earns its length with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 13 parameters, nested objects, and a rich sibling set, yet the description covers everything an agent needs to invoke it correctly: the use cases, the delivery options, the context structure, the side effect, the return value hints (per-channel counts and warnings), and the relationship to siblings. The output schema exists but the description still clarifies semantics like what happens when url is ignored or what askQuestion returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some context about the purpose of context objects and delivery targeting, but the schema still carries the heavy lifting. For example, the schema already explains env: 'test' and context.askQuestion. The description adds the overall targeting semantics and the linkedCorrelationId flow, which helps, but baseline 3 is appropriate since the schema is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: sending a one-way push notification to the user's phone and browser. It explicitly distinguishes it from ask_user, saying 'Nothing is awaited; use ask_user instead when you need an answer back.' It also has a clear SIDE EFFECT warning. This is a specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: when a long-running task finishes and the user asked to be told, when the agent hits an error it cannot resolve alone, or any 'notify me when my agent needs me' moment. It also gives an explicit exclusion: use ask_user when you need an answer back, and wait_for_answer for polling the linkedCorrelationId. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| timeoutMs | No | How long this one poll blocks, in milliseconds (default 30000, max 55000). Follow handoffAction when present, otherwise nextAction. | |
| correlationId | Yes | The correlationId from an earlier ask_user response, or the linkedCorrelationId from a send_notification with an embedded askQuestion |
| Name | Required | Description |
|---|---|---|
| hint | No | What to do next, when there is a next step. |
| note | No | Free text the user added alongside their answer. |
| value | No | 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. |
| status | Yes | The actual question state. Only pending is a live unanswered wait. |
| answered | Yes | True once the user responded. False means follow handoffAction when present, otherwise nextAction; do not guess that every unanswered state is a timeout. |
| nextAction | No | Backward-compatible next step for older clients. Follow handoffAction first when present. |
| answerSource | No | Recorded answering surface, when known. Missing provenance is not proof of a phone answer; sandbox is simulated. |
| handoffAction | No | Race-safe directive for updated clients. Takes precedence over nextAction. |
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.
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.
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.
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.
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.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
propose_scope12 fields changedInput schema / properties / allowedPaths / descriptionPrevious value: -"Globs you intend to change, e.g. [\"src/**\", \"docs/*.md\"]. Omit or leave empty to propose no path restriction, which the user is told plainly."New value: +"Globs you intend to change, e.g. [\"src/**\", \"docs/*.md\"]. File paths only: a word that is not a path (\"hubspot\", \"summer-campaign\") matches no file and makes every edit read as out of scope. A bare directory is expanded for you, so \"docs\" also covers \"docs/**\". Omit or leave empty to propose no path restriction, which the user is told plainly."Input schema / properties / offLimitsPaths / descriptionPrevious value: -"Globs you promise not to touch, e.g. [\"**/.env*\", \"infra/**\"]. These win wherever they overlap allowedPaths."New value: +"Globs you promise not to touch, e.g. [\".env*\", \"infra/**\"]. These win wherever they overlap allowedPaths. A leading \"**/\" needs a directory before it, so \"**/.env*\" is expanded for you to also cover a root \".env\"."Input schema / properties / promisesAdded value: +{
+ "description": "Boundaries that are not file paths: recipients, channels, spend limits, systems you will not open. For an agent whose work is not code (marketing, sales, support, operations), this is where the boundary goes. Shown to the user labelled \"Promised, not checked\" and recorded in the ledger, but NEVER enforced, because the gate judges a file path and these have none. Do not put these in allowedPaths.",
+ "items": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 10,
+ "type": "array"
+}Input schema / properties / sessionId / descriptionPrevious value: -"Your per-session id. Required: a scope with no session cannot be enforced, and must never leak into another run."New value: +"Your per-session id, as your client reports it for THIS run. Required, and it is the key the gate reads the contract back by: a value that matches no live session still returns ratified:true and enforces nothing. Never invent one, and never reuse one from another run."Output schema / properties / contract / descriptionPrevious value: -"The scope exactly as it was put to the user, echoed back so the agent and the human are holding the same contract."New value: +"The scope as it is STORED and gated, echoed back so you and the server hold the same contract. Paths are the EXPANDED ones: a bare directory and a leading \"**/\" each gain the variant they would otherwise have missed, so this can contain more entries than you sent. The user was shown the paths you sent, because the added twin says the same thing to a reader; the expansion only changes what the matcher covers, never what it means."Output schema / properties / contract / properties / allowedPaths / descriptionPrevious value: -"Globs the run may change. Empty means no path restriction was proposed, which the user was told plainly."New value: +"Globs the run may change, after expansion. Empty means no path restriction was proposed, which the user was told plainly."Output schema / properties / contract / properties / offLimitsPaths / descriptionPrevious value: -"Globs the run promised not to touch. These win wherever they overlap allowedPaths."New value: +"Globs the run promised not to touch, after expansion. These win wherever they overlap allowedPaths."Output schema / properties / contract / properties / promisesAdded value: +{
+ "description": "Non-path boundaries as the user saw them. Recorded, never enforced.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / enforcementNoteAdded value: +{
+ "description": "Present only when there is something true to say about the limits of this contract. Repeat it to the user rather than paraphrasing it.",
+ "type": "string"
+}Output schema / properties / enforcesAdded value: +{
+ "description": "What this contract CONTAINS that can be checked, not a promise about what the gate on this machine will do. An EMPTY array means nothing here is checked automatically: the contract is a recorded promise, and every action stays governed by the permission policy exactly as it was before. Never tell the user a boundary is enforced when this is empty.",
+ "items": {
+ "enum": [
+ "paths"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / hookSeenAdded value: +{
+ "description": "Whether any agent hook has actually reported this sessionId. FALSE means the gate will look this contract up under a key that does not exist, so nothing will be checked no matter what ratified says: fix the session id rather than proceeding as if a scope were in force. ABSENT means the check could not run, which is not evidence either way.",
+ "type": "boolean"
+}Output schema / requiredPrevious value: -[
- "correlationId",
- "ratified",
- "answered",
- "contract"
-]New value: +[
+ "correlationId",
+ "ratified",
+ "answered",
+ "enforces",
+ "contract"
+]ask_user1 field changedInput schema / properties / toolPathAdded 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"
+}ask_user1 field changedOutput schema / properties / answerSourceAdded 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"
+}wait_for_answer1 field changedOutput schema / properties / answerSourceAdded 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"
+}ask_user2 fields changedOutput schema / properties / deliveryModeAdded value: +{
+ "description": "Effective delivery policy for this decision.",
+ "enum": [
+ "push_first",
+ "push_only",
+ "notify_only",
+ "terminal_only"
+ ],
+ "type": "string"
+}Output schema / properties / policyTimeoutMsAdded value: +{
+ "description": "Policy wait window in milliseconds. Callers must also honor their host deadline.",
+ "minimum": 0,
+ "type": "number"
+}ask_user3 fields changedInput schema / properties / envAdded 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"
+}Output schema / properties / envAdded value: +{
+ "description": "Echoed when the call was test traffic.",
+ "enum": [
+ "test"
+ ],
+ "type": "string"
+}Output schema / properties / heldAdded 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"
+}cancel_question2 fields changedInput schema / properties / handoffAdded value: +{
+ "description": "True when you are cancelling because you are about to ask the same question in the current client. For the next minute the Pushary hook then lets your own question tool through instead of sending it back to the phone. Set automatically whenever a live question is cancelled.",
+ "type": "boolean"
+}Output schema / properties / askHandoffAdded value: +{
+ "description": "True when the session was marked as handing off to the current client, so the hook will not re-ask on the phone for the next minute.",
+ "type": "boolean"
+}send_notification2 fields changedInput schema / properties / envAdded value: +{
+ "description": "Set to \"test\" from a test suite. The notification is recorded in the activity feed and nothing is delivered to a phone or browser. The X-Pushary-Env: test header does the same for every call on the connection.",
+ "enum": [
+ "test"
+ ],
+ "type": "string"
+}Output schema / properties / envAdded value: +{
+ "description": "Echoed when the call was test traffic.",
+ "enum": [
+ "test"
+ ],
+ "type": "string"
+}ask_user2 fields changedInput schema / properties / waitEndsAtAdded 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"
+}Output schema / properties / waitEndsAtAdded 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"
+}ask_user1 field changedOutput schema / properties / suppressed / descriptionPrevious 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."ask_user2 fields changedInput schema / properties / questions / descriptionPrevious 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."Input schema / properties / questions / items / properties / allowOtherAdded value: +{
+ "type": "boolean"
+}ask_user2 fields changedInput schema / properties / questions / descriptionPrevious 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."Input schema / properties / questions / maxItemsPrevious value: -4New value: +1ask_user6 fields changedOutput schema / properties / handoffActionAdded 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"
+}Output schema / properties / nextActionAdded 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"
+}Output schema / properties / noDevices / descriptionPrevious 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."Output schema / properties / status / descriptionPrevious 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."Output schema / properties / status / enumPrevious value: -[
- "pending",
- "notified",
- "terminal"
-]New value: +[
+ "answered",
+ "pending",
+ "cancelled",
+ "expired",
+ "missing",
+ "unavailable",
+ "notified",
+ "terminal",
+ "stopped"
+]Output schema / properties / timedOut / descriptionPrevious 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."cancel_question4 fields changedOutput schema / properties / cancelled / descriptionPrevious value: -"True when a still-pending question was removed. False when there was nothing to remove because it was already answered, already expired, or never existed."New value: +"True when a still-pending question was removed. False when it was already terminal, missing, or unavailable; inspect status and handoffAction when present."Output schema / properties / handoffActionAdded value: +{
+ "const": "stop",
+ "description": "Stop rather than opening another answer surface when the question state is unavailable.",
+ "type": "string"
+}Output schema / properties / hintAdded value: +{
+ "description": "What to do when cancellation could not safely inspect the question.",
+ "type": "string"
+}Output schema / properties / statusAdded value: +{
+ "const": "unavailable",
+ "description": "Present when Pushary could not safely read or fence the question state.",
+ "type": "string"
+}propose_scope5 fields changedOutput schema / properties / correlationIdAdded value: +{
+ "description": "Id of the scope question. Pass it to wait_for_answer once when the first wait times out.",
+ "type": "string"
+}Output schema / properties / handoffActionAdded value: +{
+ "description": "Race-safe directive for updated clients. Takes precedence over nextAction.",
+ "enum": [
+ "cancel_then_ask_in_current_client",
+ "stop"
+ ],
+ "type": "string"
+}Output schema / properties / nextActionAdded value: +{
+ "description": "Poll one live question once; otherwise ask in the current chat whether to continue without an enforced scope.",
+ "enum": [
+ "wait_for_answer",
+ "ask_in_current_client"
+ ],
+ "type": "string"
+}Output schema / properties / statusAdded value: +{
+ "description": "The underlying scope-question state.",
+ "enum": [
+ "answered",
+ "pending",
+ "cancelled",
+ "expired",
+ "missing",
+ "unavailable",
+ "notified",
+ "terminal",
+ "stopped"
+ ],
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "ratified",
- "answered",
- "contract"
-]New value: +[
+ "correlationId",
+ "ratified",
+ "answered",
+ "contract"
+]wait_for_answer7 fields changedInput schema / properties / timeoutMs / descriptionPrevious 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."Output schema / properties / answered / descriptionPrevious 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."Output schema / properties / handoffActionAdded value: +{
+ "description": "Race-safe directive for updated clients. Takes precedence over nextAction.",
+ "enum": [
+ "cancel_then_ask_in_current_client",
+ "stop"
+ ],
+ "type": "string"
+}Output schema / properties / hintAdded value: +{
+ "description": "What to do next, when there is a next step.",
+ "type": "string"
+}Output schema / properties / nextActionAdded value: +{
+ "description": "Backward-compatible next step for older clients. Follow handoffAction first when present.",
+ "enum": [
+ "wait_for_answer",
+ "ask_in_current_client"
+ ],
+ "type": "string"
+}Output schema / properties / statusAdded value: +{
+ "description": "The actual question state. Only pending is a live unanswered wait.",
+ "enum": [
+ "answered",
+ "pending",
+ "cancelled",
+ "expired",
+ "missing",
+ "unavailable"
+ ],
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "answered"
-]New value: +[
+ "answered",
+ "status"
+]ask_user1 field changedInput schema / properties / requestIdAdded 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"
+}ask_user1 field changedInput schema / properties / questionsAdded 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"
+}ask_user1 field changedInput schema / properties / toolUseIdAdded 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"
+}ask_user1 field 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"
+}cancel_question1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "cancelled": {
+ "description": "True when a still-pending question was removed. False when there was nothing to remove because it was already answered, already expired, or never existed.",
+ "type": "boolean"
+ },
+ "correlationId": {
+ "description": "The question this result refers to, echoed back.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "cancelled",
+ "correlationId"
+ ],
+ "type": "object"
+}propose_scope1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "answered": {
+ "description": "True when the user responded at all. Answered but not ratified means they declined, so ask what scope they want rather than proceeding.",
+ "type": "boolean"
+ },
+ "contract": {
+ "additionalProperties": false,
+ "description": "The scope exactly as it was put to the user, echoed back so the agent and the human are holding the same contract.",
+ "properties": {
+ "allowedPaths": {
+ "description": "Globs the run may change. Empty means no path restriction was proposed, which the user was told plainly.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "doneWhen": {
+ "description": "What finished means for this run, as the user saw it.",
+ "type": "string"
+ },
+ "offLimitsPaths": {
+ "description": "Globs the run promised not to touch. These win wherever they overlap allowedPaths.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "allowedPaths",
+ "offLimitsPaths",
+ "doneWhen"
+ ],
+ "type": "object"
+ },
+ "note": {
+ "description": "Present only when the scope is not in force, saying what to do instead of proceeding.",
+ "type": "string"
+ },
+ "ratified": {
+ "description": "True only on an explicit yes. The contract is in force for this session only when this is true; anything else means proceed as if no scope was agreed.",
+ "type": "boolean"
+ },
+ "value": {
+ "description": "The raw answer behind ratified, \"yes\" or \"no\".",
+ "type": "string"
+ }
+ },
+ "required": [
+ "ratified",
+ "answered",
+ "contract"
+ ],
+ "type": "object"
+}send_notification1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "delivery": {
+ "additionalProperties": false,
+ "description": "Per-channel outcome. The two channels are independent with no cross-fallback, so each reports its own result.",
+ "properties": {
+ "mobile": {
+ "additionalProperties": false,
+ "properties": {
+ "recipients": {
+ "description": "Phones that accepted the push.",
+ "type": "number"
+ },
+ "status": {
+ "description": "Why mobile delivery reached nobody, present only when it reached nobody.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "recipients"
+ ],
+ "type": "object"
+ },
+ "web": {
+ "additionalProperties": false,
+ "properties": {
+ "recipients": {
+ "description": "Browsers that accepted the push.",
+ "type": "number"
+ },
+ "status": {
+ "description": "Why web delivery reached nobody, present only when it reached nobody.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "recipients"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "web",
+ "mobile"
+ ],
+ "type": "object"
+ },
+ "hint": {
+ "description": "What to do next, when there is a next step.",
+ "type": "string"
+ },
+ "linkedCorrelationId": {
+ "description": "Present only when context.askQuestion embedded a decision prompt. Pass it to wait_for_answer to collect the response.",
+ "type": "string"
+ },
+ "sent": {
+ "description": "Total devices reached, web plus mobile. Zero is a successful call that found nobody to deliver to, not an error.",
+ "type": "number"
+ },
+ "warning": {
+ "description": "Present only when the notification reached zero devices, naming what the user has to connect.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}wait_for_answer1 field 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"
+}activate_flowcount_subscriberscreate_campaigncreate_flowcreate_templateget_campaignget_campaign_statsget_subscriberlist_campaignslist_flowslist_sessionslist_subscriberslist_templatespause_campaignpause_flowsend_campaign
Add one secure layer between your agents and this server.