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-approval lifecycle: asking, waiting on an answer, and withdrawing a pending question. The descriptions explicitly state when to use wait_for_answer versus ask_human, and cancel_question is clearly bounded to pending status. No pair can be reasonably confused.
All three names follow the same snake_case verb_noun pattern (ask_human, cancel_question, wait_for_answer). The verbs are distinct and accurate, and the nouns identify the acted-upon resource or counterpart.
Three tools is a tight, well-scoped surface for a single-purpose approval server, and each one earns its place. It sits at the low end of the comfortable range, with no redundant operations but also no room for conveniences.
The core lifecycle is covered: question, poll for status, and cancel, with expiration and error states documented. Minor gaps exist, such as no way to list or look up outstanding questions by id without blocking on wait_for_answer, but agents can work around this by tracking question_ids.
Send a question to the user's phone and return their answer. It reaches them in Telegram, or by email (WhatsApp or Signal when connected), with one button per option. Use it when the user wants to approve or decide something outside the conversation, for example before you pay, send a message or an email on their behalf, delete, publish or sign up for something, or when they ask you to check with them through Aval or on their phone. Not for things the user already approved in the conversation, or for questions you can answer yourself. Ask one decision per call. Write question in the user's language so that it makes sense on its own, give up to 6 short options (Yes / No when left out), and put the details they need in context. The call waits up to 45 seconds. Status "answered" comes with answer (the chosen option), answer_index and an optional comment from the user. Status "pending" comes with a question_id: call wait_for_answer until the status changes, and wait for the answer before carrying out the action. Status "expired" means no approval. Errors: "subscription_required" (the user can connect Telegram or subscribe), "rate_limited" (more than 6 questions a minute).
| 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 are sparse (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the description carries real weight and does: it discloses the 45-second wait, the three terminal statuses and their meanings ('expired' means no approval), the warning to wait before acting, and two named error conditions including the 6-questions-per-minute rate limit. None of this contradicts the annotations — the tool itself creates a question rather than destroying anything.
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?
It is one dense block of prose, but nearly every sentence earns its place and it is front-loaded with the core action before moving to routing, constraints, and result shapes. Some parameter guidance overlaps the schema text verbatim in spirit, which keeps it from a 5 on efficiency.
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 must explain return values — and it does, enumerating answered/pending/expired, the fields that accompany each (answer, answer_index, comment, question_id), and the required follow-up call. Errors and rate limits are also covered, which is more than sufficient for a 6-parameter tool.
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 parameter descriptions are already detailed, so the baseline is 3; the description adds guidance on intent rather than restating bounds — write `question` in the user's language so it stands alone, default Yes/No when options are omitted, and put decision details in `context`. 'Ask one decision per call' adds a constraint not expressed in the schema, though a fair amount of the parameter advice duplicates what the schema already says.
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 — 'Send a question to the user's phone and return their answer' — and names the delivery channels (Telegram, email, WhatsApp/Signal). It also distinguishes itself from the sibling wait_for_answer by explaining the 45-second wait and the pending handoff, so an agent can route correctly without opening any schema.
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 explicit when-to-use triggers (before paying, sending a message or email, deleting, publishing, signing up, or when the user asks to be checked with via Aval), explicit when-not conditions (already approved in conversation, or questions the agent can answer itself), and the follow-up path for pending results. It even constrains granularity: 'Ask one decision per call.'
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.
| 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 non-readOnly, so the safety profile is covered. The description adds real value beyond that: the live-status precondition ('Only works while the status is pending') and the cost model ('Free'), neither of which appears in annotations. It stops short of saying what error or state results if the question is already answered, but the annotation set covers the mutation risk.
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 short sentences: action and effect first, then usage conditions, then the precondition and cost. No filler, and the routing information is 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?
For a one-parameter mutation tool with a fully described schema and meaningful annotations, the description covers purpose, triggers, and the pending-only constraint. No output schema exists, so only the post-call failure behavior is left implicit.
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 sole parameter, question_id, is documented in the schema as 'returned by ask_human, copied exactly'. The description adds no extra syntax or format guidance for it, so the baseline 3 for schema-heavy definitions 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') and resource ('a question that is still pending') plus the consequence ('the human can no longer answer it'). It is clearly distinguishable from siblings ask_human (creates) and wait_for_answer (blocks), since this one terminates a pending 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?
Gives an explicit when-to-use clause with three concrete triggers: the human answered another way, the task changed or was dropped, or a corrected version is about to be asked. It also names the precondition (status must be 'pending'), so the agent knows when the call will fail.
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.
Let your AI agents ask you for decisions and get your answers back, from your phone or the web.
A second look before your AI agent buys, sends, books, shares, signs up, or connects an app.
Give any AI agent a way to ask a person — for approval, a decision, an answer or a review.
Add one secure layer between your agents and this server.
