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.
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 |
|---|---|---|---|
| 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. | |
| 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 |
|---|---|---|
| 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. |
| 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. |
| expiresInSeconds | No | How long the question stays answerable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly=false and destructive=true, which is a thin safety profile. The description carries the burden and does so thoroughly: it discloses that it sends real push notifications, blocks at most 55 seconds, may time out into wait_for_answer/cancel_question, and reports terminal states for cancelled/expired/missing questions. No contradiction with annotations exists.
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 with operational guidance and delivers the core behavior in the first sentence. Some repeated instructions about polling and cancellation could be tightened, but each sentence adds actionable value for a complex approval tool.
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 complex, blocking, destructive tool with 26 parameters and 4 siblings, the description covers invocation, timeout recovery, cancellation, response shape (answerUrl, nextAction), targeting, and client compatibility. Output schema exists so return values don't need to be repeated. The description is complete enough to use safely.
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, but the description adds significant context: it explicitly says avoid requestId/toolUseId for ordinary callers, explains the wait_for_answer conversation flow, shows example values for repoKey and agentName, and clarifies the questions field is runtime-populated. This goes well beyond the schema alone.
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 blocks on a phone push question until answered, explains three question types, and includes a side-effect warning. It distinguishes itself from wait_for_answer, cancel_question, and send_notification by explicitly explaining when to use it and the wait/poll/cancel flow.
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 is explicit about when to use the tool (risky/irreversible steps, picking options, supplying missing input), when not to (polling separately), and how to handle timeouts (wait_for_answer then cancel_question then re-ask). It also states that no Claude subscription is required and that it works from various MCP clients, which gives clear usage context.
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 |
|---|---|---|---|
| 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. |
| 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?
Goes beyond the annotations by disclosing that questions expire after 10 minutes, pending-only effects, return semantics for both cancel paths, and the needed unavailable-status behavior. This is not inferable from idempotentHint or destructiveHint alone.
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?
Front-loaded with the action and effect, then efficiently covers use cases, expiry, return semantics, and edge cases. Every sentence earns its place; no filler or repetition.
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 one-parameter, idempotent operation with an output schema, this covers when to call it, what it affects, what it returns, and what to do in the no-op/unavailable case. The only mild ambiguity is the exact shape of the false result, but the output schema covers return values.
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?
With 100% schema description coverage, the schema fully documents correlationId, its UUID format, and its meaning. The tool description adds essentially nothing about the parameter. Baseline 3 is appropriate.
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?
States a distinct verb and resource: 'Retract a pending question' with a clear effect ('can no longer be answered'). The use-case listing makes the purpose unmistakable and separates it from the ask/wait sibling tools.
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?
Explicitly gives when to use it: when a question became irrelevant before the user replied, with concrete triggers. It also gives an important exclusion—only pending questions are affected—and instructs the agent to stop rather than open another surface when status is unavailable, though it does not name sibling alternatives explicitly.
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/", "/*.test.ts"). Shell commands are NOT scoped here, they stay governed by the permission policy. Scope lives for this session only and is never inherited by another run. Returns { correlationId, ratified, answered, value }; only ratified:true means the contract is enforced. 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. | |
| 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. Required: a scope with no session cannot be enforced, and must never leak into 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"]. 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. |
| 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 exactly as it was put to the user, echoed back so the agent and the human are holding the same contract. |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond what the annotations already declare by disclosing the blocking behavior, the timeout/poll/retry flow, late ratification, cancellation race handling, and the exact retry semantics. It also surfaces a real side effect: "SIDE EFFECT: sends a real push notification." The caveat "Never describe a client-only agreement as ratification" and the session-only contract both add a strong trust boundary. No contradiction with annotations; in fact, the detail explains why destructiveHint=true.
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 front-loaded with the purpose and then each subsequent sentence carries nonzero behavioral content, covering call timing, scope contract, enforcement, exclusions, session lifetime, return semantics, and runtime edge cases. Sentences are not redundant with the parameters. It is a long single paragraph and the race-condition logic could be tightened into structured subpoints, but no sentence is wasted.
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 complex tool with 7 parameters, an output schema, 4 annotations, and 4 siblings, this description covers the full agent lifecycle: call site, the blocking wait behavior, what the return object means, how to recover on timeout, when to cancel, how to handle a racing late answer, and what is explicitly out of scope (shell commands). An agent given this description would be able to use the tool correctly without accessing any other 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?
Schema description coverage is 100%, so the baseline is 3 per the rubric. The description adds a glob syntax hint ("src/**", "**/*.test.ts") that the schema doesn't spell out, and it maps the narrative terms (paths you intend to change, areas you promise to leave alone, definition of done) to allowedPaths, offLimitsPaths, and doneWhen. However, the schema already carries the full per-parameter meaning, so the description only marginally adds semantic value.
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 opening line states a specific verb-resource behavior: "Propose what this run will touch and block until the user ratifies it." This identifies the tool as a human-ratification contract for work boundaries, clearly distinct from sibling tools like ask_user, send_notification, or wait_for_answer. The first sentence and the "Call ONCE at the start of a multi-step run" instruction make the purpose impossible to miss.
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?
When to use is explicit: "Call ONCE at the start of a multi-step run, before doing work." When-not logic is also specified: "Shell commands are NOT scoped here, they stay governed by the permission policy" and "Scope lives for this session only and is never inherited by another run." It never names an alternative sibling tool (e.g., ask_user or wait_for_answer) as the substitute to use instead, so it stops just short of full alternative routing.
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 |
|---|---|---|---|
| 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 |
|---|---|---|
| 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?
Even though annotations include destructiveHint=true and readOnlyHint=false, the description adds crucial context: 'Nothing is awaited' (fire-and-forget behavior) and a SIDE EFFECT warning that it 'delivers real notifications to real devices immediately.' This goes beyond the boolean annotations and explains the real-world impact, fully aligning with the destructive hint without contradicting it.
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 but well-structured, leading with purpose and then covering usage, targeting, context, side effects, and return. It earns its length for a 12-parameter tool, though some asides like 'Works from Claude Code, Codex, Cursor, Hermes...' are non-essential and could be trimmed. Overall it is efficient and front-loaded.
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 description covers usage scenarios, targeting options, the rich context detail page, askQuestion embedding, side effects, and return characteristics (per-channel counts and warnings). With an output schema present, it doesn't need to fully restate return types, and it still provides a complete operational picture for the agent to invoke this tool 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?
The description significantly enriches the schema (which already has 100% parameter coverage) by explaining the interaction between url and context ('Ignored if context is provided'), how targeting fields narrow delivery, and the askQuestion flow returning a linkedCorrelationId for use with wait_for_answer. It also clarifies the meaning of deliver counts and zero-device warnings, adding semantics far beyond the schema descriptions.
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?
Opens with a specific verb and resource: 'Send a one-way push notification to the user's phone and browser.' It also clearly distinguishes itself from sibling ask_user by stating 'use ask_user instead when you need an answer back.' This makes the tool's purpose unambiguous and differentiates it from alternatives.
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?
Provides explicit when-to-use guidance: 'Reach for this when a long-running task finishes... when the agent hits an error it cannot resolve on its own, or for any 'notify me when my agent needs me' moment.' It also gives a clear exclusion: 'use ask_user instead when you need an answer back,' and mentions wait_for_answer for polling the response. This is textbook 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. |
| 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 though annotations carry readOnlyHint and idempotentHint, the description adds extensive behavioral context: blocking semantics per-poll with 30s default and 55s max, the cancel_then_ask_in_current_client handoff behavior, the one-second re-poll race resolution, the distinct response states (pending, cancelled, expired, missing, unavailable) with 'cancelled/unavailable mean stop, not re-ask' semantics, and a note on legacy clients for nextAction. There is no contradiction with the 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?
The description is long but information-dense — every sentence carries either a behavioral rule or a boundary condition that the agent needs to act correctly. It's front-loaded with the primary purpose and trigger conditions. It is not verbose for its set of distinct facts, though a sentence or two could potentially be tightened if the goal were extreme brevity.
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 the actual complexity of a result-style tool with an output schema, the description covers all the important execution nuances: the meaning of each response state, how to handle a live-but-unanswered question, what to do on cancellation calls, and legacy client behavior. It also covers the race-resolution via a follow-up 1s poll. The output-structure detail of the schema rounds out the documentation without leaving open questions.
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?
Parameter semantics is already handled well by the input schema: both the correlationId and the timeoutMs are fully described, including acceptable formats, defaults, and min/max limits in the schema itself. The description echoes those facts and adds the contextual connection to ask_user/send_notification flows, but does not materially exceed what the schema already conveys; the schema gives a 3, and the description's added value is positive but marginal.
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?
A very specific verb+resource: "Poll once for the user's answer to a previously created question". It names the exact trigger conditions (after ask_user times out, after ask_user with wait:false, or with a linkedCorrelationId from send_notification), which sharply differentiates it from the other siblings — especially ask_user, who creates the question rather than polls it.
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 when-to-use conditions are explicit and enumerate the exact predecessor scenarios, so the agent knows precisely when to invoke this instead of the clearly referenced alternatives ask_user and send_notification. The main gap is that it doesn't have an explicit when-not-to-use clause, though the prerequisite 'previously created question' effectively closes that gap by implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Each tool has a clearly distinct role: ask_user blocks for a decision, send_notification is one-way, wait_for_answer polls an existing question, cancel_question retracts a pending one, and propose_scope is a specialized ratification flow. The only potential overlap is ask_user versus propose_scope, but the scope-specific contract and 'call ONCE at the start' guidance make the boundary clear.
All five tools follow the same imperative verb_noun snake_case pattern: ask_user, cancel_question, propose_scope, send_notification, wait_for_answer. Even though the verbs differ, the structure is uniform and predictable.
Five tools is well-scoped for a push-notification and human-in-the-loop interaction server. There is no redundancy or padding; every tool maps to a distinct stage in the question/notification lifecycle.
The server covers the full interaction lifecycle: create a question (ask_user), wait for its answer (wait_for_answer), cancel it if obsolete (cancel_question), send one-way alerts (send_notification), and ratify scope before multi-step work (propose_scope). No obvious dead ends or missing critical operations exist for the stated purpose.