Your agent asks you before it acts. You answer with one tap on your phone. Human-in-the-loop.
Scored across 3 tools
Each tool maps to a distinct phase of the human-in-the-loop decision lifecycle: ask creates a question, wait polls its status, and cancel withdraws it. The descriptions explicitly delimit boundaries (cancel only works while pending, wait never re-asks), so an agent can reliably pick the right one.
All three tools follow a clean snake_case verb_noun pattern (ask_human, cancel_question, wait_for_answer). The convention is applied uniformly with no mixed styles or vague verbs.
Three tools is a tight, well-scoped surface for an approval-gating service, and each one is necessary: without any single tool the ask/wait/cancel loop breaks. No tool feels redundant or padded.
The core lifecycle (ask, poll, cancel) is fully covered including terminal states like expired and cancelled. A minor gap is the absence of a way to list or recover outstanding question_ids, which matters if an agent loses track of a pending question.
Ask the human you work for to decide something, and get their answer from their phone. WHEN: before any action that is hard to undo or that they should decide: paying or buying, sending an email or a message on their behalf, deleting, publishing, signing up, sharing their data, or choosing between options they care about. Also whenever they tell you to check with them, ask them or get their OK ("through Aval", "on my phone"): then call this tool, never write the question in the conversation instead. Do not use it for things they already approved, or for questions you can answer yourself. HOW: one decision per call. Write the question in the human's language, short and self-contained (it is read on a phone lock screen, without this conversation); give 2 to 6 short options, one button each; put the details they need (amounts, recipients, the draft to send, links) in context. They get it in Telegram or by email (WhatsApp, Signal or iMessage when available) and answer with one tap. The call waits up to 45 seconds. Result: status "answered" with answer (the chosen option, exactly as written), answer_index and maybe a comment from the human: follow it, including the comment. Status "pending": they have not answered yet; call wait_for_answer with the question_id, again and again, and do not act meanwhile. Never assume or guess an answer. Costs one credit; error "no_credits" means the owner must buy more.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Everything the human needs to decide, plain text, 2000 characters max: amounts, recipients, dates, the exact text you will send, links to check, what happens with each option. Shown under the question. | |
| options | No | 2 to 6 distinct answer buttons, 40 characters max each, in the human's language, the most likely first. Make each one an action you know how to carry out. Leave it out for Yes / No. Example: ["Pay", "Wait until Monday", "Don't pay"] | |
| question | Yes | The question, in the human's language, at most 300 characters, understandable without the conversation: say what you will do and to whom. Example: "Pay the OVH invoice of €42.90 now?" | |
| agent_name | No | Who is asking, shown to the human so they know which agent or task it is. Example: "Claude Code · billing" | |
| wait_seconds | No | How long this call waits for the answer before returning "pending" (0 to 45, default 45). Keep the default. | |
| expires_in_minutes | No | How long the human can answer, in minutes (1 to 10080, default 60). After that the question expires, which means no approval. Give more time when nothing is urgent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, which says little about runtime behavior. The description supplies the substantive traits: a 45-second wait, 'answered' vs 'pending' statuses, the answer_index/comment return shape, the requirement to retry via wait_for_answer and not act meanwhile, one-credit cost, and the no_credits error. This is rich disclosure well beyond 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?
Long but deliberately structured with WHEN and HOW markers and front-loaded critical guidance. Some parameter detail duplicates the schema verbatim, so a few sentences could be trimmed, but every section contributes operational value.
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 6-parameter, non-idempotent, open-world tool with no output schema, the description covers everything an agent needs: delivery channels, the blocking window, both result statuses and their fields, the retry loop, credit/error handling, and the anti-guessing rule.
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% and each parameter already carries a detailed description (including limits, examples, defaults and the 'expires means no approval' rule). The description's parameter guidance (one decision per call, 2-6 short options, details in context) largely restates the schema, so the baseline 3 applies.
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 specific verb (ask) and resource (the human you work for) plus the mechanism (answer from their phone). It actively distinguishes itself from siblings by naming wait_for_answer for pending questions and by warning never to write the question in the conversation instead.
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 gives an explicit WHEN list (irreversible or owner-decided actions: paying, sending, deleting, publishing, sharing data, choosing), an explicit escalation trigger (whenever they say to check with them), and explicit exclusions (things already approved, questions the agent can answer itself). Alternatives are named, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Withdraw a question that is still pending, so the human can no longer answer it. Use it when the question no longer matters: the human answered you another way, the task changed or was dropped, or you are about to ask a corrected version. Only works while the status is "pending". Free, but the credit spent by ask_human is not refunded.
| Name | Required | Description | Default |
|---|---|---|---|
| question_id | Yes | The `question_id` returned by ask_human, copied exactly. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds real value beyond them by disclosing the state precondition (must be pending), the irreversible effect on the human, and the non-refund of the ask_human credit.
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?
Three tight sentences with zero filler, front-loading the action and effect before moving to usage conditions and the cost caveat. 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?
Covers purpose, preconditions, usage triggers, and the cost consequence for a destructive one-parameter tool with full schema coverage and no output schema. The only minor gap is that it does not describe what a caller receives on success or failure.
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% and the single question_id parameter is fully documented in the schema as coming from ask_human. The description adds no syntax or sourcing detail beyond that, so the baseline 3 applies.
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 specific verb (withdraw) on a specific resource (a still-pending question) and names the effect (the human can no longer answer it). Combined with the references to ask_human, it is clearly distinguishable from the sibling question 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?
Provides explicit when-to-use conditions: the human answered another way, the task changed or was dropped, or a corrected version is about to be asked. It also states the hard precondition ('Only works while the status is "pending"'), which is exactly the routing information an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait up to 45 seconds for the human's answer to a question asked with ask_human, then return its status. Call it whenever ask_human or a previous wait_for_answer returned "pending", right away and as many times as needed: the human may take minutes to answer. Statuses: "pending" (still waiting: call this tool again, do not act yet), "answered" (answer is the chosen option, comment an optional note: follow both), "expired" (nobody answered in time: treat it as no, do not act), "cancelled". Free, does not ask the human again.
| Name | Required | Description | Default |
|---|---|---|---|
| question_id | Yes | The `question_id` returned by ask_human, copied exactly. | |
| wait_seconds | No | How long to wait before returning "pending" (0 to 45, default 45). Use 0 only to check without waiting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds behavior those hints cannot convey: the 45-second ceiling, that it does not re-ask the human, that it is free, and that an "expired" status must be treated as a no with no further action. That is exactly the extra context the annotations leave open.
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-loads the core action and duration, then the call condition, then a compact status glossary. Every clause carries operational meaning (when to call, what each status means, what to do) 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?
There is no output schema, so the description takes on the full burden of documenting returns and does so: it enumerates pending, answered (with answer and comment fields), expired, and cancelled, and states the required agent behavior for each. Nothing needed to call 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?
Schema coverage is 100%, so both question_id and wait_seconds are already documented in the schema, including the 0-45 range and default. The description reinforces the wait ceiling and pending semantics but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.
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 specific verb and resource ('wait ... for the human's answer to a question asked with ask_human') plus the scope ('up to 45 seconds') and the return ('its status'). This clearly separates it from ask_human (which asks) and cancel_question (which aborts), so an agent can route without opening schemas.
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?
Explicit trigger: call it whenever ask_human or a previous wait_for_answer returned "pending", 'right away and as many times as needed.' It also gives the counter-condition ('the human may take minutes') that justifies repeated polling, and specifies what to do for each non-pending status.
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.
ask_humancancel_questionwait_for_answerNotifications you can answer: agents push to your phone and wait for your approval or reply.
Give any AI agent a way to ask a person — for approval, a decision, an answer or a review.
Human-in-the-loop approval for agent actions, with verifiable action-bound receipts.
Lets AI agents use a real human as a tool: visual checks, taste, phone calls, unblocking, approvals
Add one secure layer between your agents and this server.
