Available Tools
All MCP tools exposed by the Pushary server
The tools available depend on your key and plan. Connector-scoped connections
expose the five agent tools: send_notification, ask_user, propose_scope,
wait_for_answer, and cancel_question. Full keys also expose fleet and push
platform tools. Partner and Enterprise connections add the four durable
Partner decision tools.
Notifications
send_notification
Send a push notification to subscribers. Target by subscriber IDs, external IDs, or tags. If no targeting is specified, sends to all active subscribers.
Prop
Type
Delivers real notifications to real users immediately.
Human-in-the-Loop
ask_user
Send a question to the user via push notification. Supports three question types: confirm (yes/no), select (multiple choice), and input (free text).
Prop
Type
Waits by default and returns the answer when one arrives within the policy window.
Check answered and value: a recorded "no" is not approval. Updated clients
follow handoffAction first when present, otherwise nextAction. On a live
timeout, call wait_for_answer once. In Updates (notify_only) mode the
notification is awareness-only and the decision stays in the current client;
Terminal mode keeps it in the client without a phone push. Questions expire after
10 minutes. Show the returned answerUrl when reporting a waiting question.
For a tool approval, also pass toolTarget (up to 80 characters). The hook sets
sessionId and machineId automatically. See
Human-in-the-loop for the complete flow.
propose_scope
Propose the boundary of one agent run. Returns ratified, answered,
correlationId, enforces, and the stored contract.
Prop
Type
Only ratified: true establishes the contract. An answered refusal is different
from no answer. Follow returned handoff directives for an unanswered proposal.
Scope narrows file access; it does not authorize risky actions within those paths.
enforces reports what the contract contains that can be checked, not what
the gate on a given machine will do. An empty array means nothing in the
contract is checked automatically: it is a recorded promise, and every action
stays governed by the permission policy exactly as before.
Only file paths are enforced, and only on tool calls that carry one (Edit,
Write, MultiEdit). Shell commands, reads, web requests and MCP tools carry
no path, so a contract says nothing about them. A run that changes no files
(marketing, sales, support, operations) belongs in promises: a campaign or
account name in allowedPaths matches no file at all. Enforcement also requires
a supported hook installation.
hookSeen: false means no hook has ever reported that sessionId. The contract
is stored under a key the gate will never read, so it checks nothing. Send the
session id your client reports for this run, or call list_sessions and match
on the working directory.
After a Pushary release, one propose_scope call can fail until your client
re-lists the tools. An MCP client caches the tool list it fetched when the
session opened. Pushary's tool schemas are strict, so a client still holding a
list from before a release rejects a response that carries a field added by it.
It affects one call and fixes itself: the client re-lists and the next call succeeds. Restart the session, or reconnect the MCP server, to clear it immediately. Long-lived sessions are the ones that see it, because they are the ones holding an old list.
wait_for_answer
Long-poll for the user's response. Blocks until the user responds or the timeout is reached.
Prop
Type
Returns { answered: true, status: "answered", value } when answered. Otherwise it distinguishes pending, cancelled, expired, missing, and unavailable. Follow handoffAction when present, otherwise nextAction. Poll one live question once; if it is still pending, cancel it before asking in the current client. If cancellation returns handoffAction: "stop", stop. Otherwise, if cancellation returns false, poll once for 1 second and honor any answer that won the race. An unavailable state stops the handoff until it can be safely retried.
cancel_question
Cancel a pending question so it can no longer be answered.
Prop
Type
Returns { cancelled: true } when a pending question was removed. False means it was already answered, expired, missing, or unavailable; if the response includes handoffAction: "stop", stop rather than opening another answer surface.
list_sessions
Read-only. Returns your site's live agent sessions (keyed by machine + session) and any pending approval questions, so you can see which of your parallel agents is blocked. Does not start, stop, or steer agents, and sends no notification.
Prop
Type
Returns { sessions, pendingQuestions }. Each session includes agentType, agentName, machineId, sessionId, computedStatus (active / idle / waiting / offline / errored), lastAction, lastSeenAt, and a human-readable timeAgo. Scoped to the API key's site — there's no parameter that can read another tenant. See the Multi-Agent Control Panel for what each status means.
This is the only agent-facing read of your fleet. It's safe to poll, performs zero writes, and is the right tool for a supervising agent that wants to find the blocked session.
Partner decisions
Use these for your product's end-users. They use the durable Decisions API, with
a default lifetime of one hour and a maximum of 24 hours. They are separate from
the operator-facing ask_user flow. See Partner setup.
enroll_end_user
Takes externalId (1–256 characters), or uses the recipient bound to the key.
Returns externalId, universalLink, deepLink, and expiresInSeconds.
Show the link to the user; they must complete app or supported browser enrollment.
Generating a link alone does not register a device.
create_decision
Creates asynchronously. Requires question (up to 500 characters) and a recipient
through externalId or a bound key.
| Parameter | Meaning |
|---|---|
type | confirm (default), select, or input |
options | 2–20 options of up to 200 characters for a select question |
context | Background, up to 2,000 characters; subject to secret redaction |
agentName | Product or agent label, up to 120 characters |
idempotencyKey | Stable operation key, up to 200 characters; reuse for retries only |
expiresInSeconds | At least 60; clamped to 24 hours; defaults to one hour |
callbackUrl | Signed answer callback; verify it before trusting the body |
requireReachable | Refuse with 409 when no recipient push channel is registered |
Returns decisionId, status, answered, and pollUrl, plus reachability
information when available. A fresh decision also includes decisionPageUrl.
Only an answered confirm decision with an affirmative value is approval.
The MCP create tool exposes the parameters above; use REST or the SDK for
structured action fields, presentation, or approvalUrl.
get_decision
Takes decisionId and optional waitSeconds (0–20). Returns the durable state.
Poll the same ID while it is pending; stop on an answer, expiry, or cancellation.
Do not apply the operator tool's one-poll-then-chat handoff to this workflow.
cancel_decision
Takes decisionId. Returns { decisionId, cancelled, status }. A false
cancelled result means this call did not retract a pending decision; read the
current state before deciding what happens to your workflow.
Use a bound key in a trusted per-user runtime. It fixes the recipient and limits access to that user's decisions. It still carries authority to submit answers, so do not put it in model-visible text.
Subscribers
list_subscribers
List push notification subscribers with optional filters. Returns a paginated list.
Prop
Type
get_subscriber
Get full details of a single subscriber by ID, including browser, OS, location, tags, and activity.
Prop
Type
count_subscribers
Get subscriber counts broken down by status: total, active, and unsubscribed. No parameters required.