Skip to main content

Decisions MCP Tools

Field-by-field reference for the ask_human, get_decision, cancel_question, send_followup and get_involvement tools Daintree hands an agent at launch, with their statuses, size limits and expiry rules.

Updated
Reviewed

An agent you've enabled for Decisions gets a daintree-decisions MCP server at launch with five tools. Agents read the tool descriptions themselves, so you rarely need this page to use Decisions. It's here for writing a runbook or skill that calls the tools on purpose, such as an approval gate, and for knowing the limits before an agent runs into them.

The contract below comes from the @daintreehq/decisions-client 0.8 library Daintree ships. Limits come from the relay's protocol limits.

The Five Tools

ToolRequiredReturns
ask_humanquestionAt once: a question_id, the requirement level in force, and an instruction naming the question by a short alias such as q-4. The answer comes later, typed into the terminal.
get_decisionquestion_idThe question's status, the answer and its thread
cancel_questionquestion_idCancellation requested., with status cancelling
send_followupquestion_id, text, expects_replyAt once: Queued in q-4's thread and sent in the background.
get_involvementNothingHow involved you want to be right now

The alias is for people. get_decision, cancel_question and send_followup take the question_id, so a runbook that checks an answer later should keep it. An agent sees only the questions its own terminal owns: the one that asked, unless you moved an answer elsewhere with Choose destination. It can't read, cancel or post on another terminal's questions.

ask_human

Asks you a question the agent shouldn't decide for itself. It never waits for the answer.

FieldWhat it is
questionRequired. The question, self-contained, up to 8,000 characters.
contextBackground you need to decide, up to 32 KiB.
kindchoice (pick one option), approval (offered as Approve and Reject unless the agent gives options), text (an open answer) or mixed (pick an option or write an answer instead; the default when there are options).
optionsUp to 12, each with an id, a label of up to 240 characters and an optional description of up to 1,000. You pick at most one; under mixed you can write an answer instead.
attachmentsUp to 8 screenshots, each with a local_resource_id (the image's path), an optional role (before, after, reference or other) and optional alt text.
requested_requirementhuman-required, proxy-ok or proxy-first. A question without a gate needs your own answer unless you've turned on Allow proxy answers and the agent asks for proxy-ok or proxy-first. Under a gate, it can only make the question stricter.
workflow_gate_idA gate Daintree registered, such as design-review/final. The gate's choices replace options, so leave options out, and it can refuse free text and require attachments.
expires_atAn ISO time, within the expiry limits. Leave it out for your default.
preparationHow the agent prepared the question under your involvement preference. Required inside it: agents_consulted (how many other agents it actually consulted, 0 to 64) and outcome (agreed, split or not-run). Optional: a summary of up to 2,000 characters and the preference_revision it read (null if none was available). Your phone shows it as the agent's own account. It never answers or approves anything.
correlation_idUp to 64 characters. Asking again from the same terminal with the same id returns the existing question, as long as the attachments, the gate and the requirement level are the same. Change any of those and it's a new question. Use a fresh id for a genuinely new question.

Attachment Limits

  • Screenshots are paths relative to the folder the agent's terminal was launched in, and must stay inside it once symlinks are followed.
  • Each must be a PNG, JPEG or WebP image of up to 20 MiB, with 64 MiB in total per question. SVG is refused.
  • A terminal can have 10 questions open at once.
  • Going the other way, you can attach up to 4 photos to an answer or follow-up on your phone, each up to 10 MiB.

Expiry Limits

A question with no expires_at waits for your default expiry, seven days unless you changed it. An agent can ask for another time, up to 30 days, or up to your default when that's longer; a longer request is cut back to that limit rather than refused. With the default set to Never, it can ask for any time up to the relay's limit of 366 days, less two minutes for clock skew. A question is refused when its expiry would land beyond that limit, or less than a minute from now. The design-review/final gate sets no expiry of its own.

get_decision

Reads back a question the agent's terminal owns. The useful fields:

FieldValues
statusqueued, open, proxy-answered, human-answered, cancelled, expired or publish-failed
provenancehuman, proxy or null
answered_onFor your own answer, phone (a phone or tablet) or computer (the Decisions inbox or question view on this computer). Null otherwise. Both are your answer. Each answer entry in the thread carries it too.
closed_reasonWhy a closed question has no answer: declined (you dismissed it), withdrawn (you withdrew it, or the agent canceled it) or expired, and null otherwise. None of them authorizes anything.
choice and textThe option you picked and anything you wrote
reviewed_digests_matchtrue only if your answer covered exactly the images attached
threadAnswers and follow-up messages in order

The thread holds two kinds of entry. An answer entry carries its revision, its source (human, proxy or system), the choices picked, its text and whether it was delivered. A message entry is a follow-up: its side (agent or human), expects_reply, its text, any images, and for one of yours, where you sent it from (sent_from: phone or computer) and how its delivery went.

Only status: human-answered with provenance: human is your decision. A follow-up never is, and expired never authorizes anything.

cancel_question

Asks for a question that's no longer needed to be withdrawn. It returns at once with status: cancelling; call get_decision to see it reach cancelled. It can't undo a question you already answered. The schema accepts a reason of up to 500 characters, but Daintree doesn't pass it on. The tool is marked as destructive, so an agent CLI that confirms destructive tool calls may ask you before running it.

send_followup

Posts in the thread of a question the agent's terminal owns, instead of asking a new question: to clarify it, reply to you, or ask something more. text is up to 16 KiB. Set expects_reply to true when the agent needs you to reply, which brings an answered question back to Needs you on your phone, or false for a note.

  • Like a question, it's saved on this computer first and sent once the relay is reachable.
  • It never answers the question, changes your answer or satisfies a gate, and it's never typed into a terminal.
  • A question's thread holds at most 200 messages, counting both sides. A terminal can't post on a question that was withdrawn or expired.
  • A relay older than 0.4.0 doesn't accept follow-ups. Update the relay to use them.

get_involvement

Reads how involved you want to be right now, as you set it on your phone or in the Decisions inbox. Agents are told to read it before they prepare a question and again just before ask_human, so a change reaches agents that are already running. It takes no arguments, reads this computer's copy, and never asks you anything.

FieldValues
statusavailable or unavailable
modeinvolve-early (ask while still exploring the options) or recommend (consult other agents, then bring a recommendation or the disagreement)
consult_countHow many other agents to consult under recommend
normal_mode, override_active, untilYour usual mode, whether a temporary mode is in force (true or false), and when it ends
set_at, last_synced_atWhen the preference was set, and when this computer last confirmed it with the relay
revisionThe version read, which ask_human's preparation can name
staletrue when the copy may be out of date: the connection to the relay is retrying, or a change was heard of and hasn't been checked yet
reasonWhy it's unavailable: not-synced, not-set, unsupported, signer-revoked or device-revoked

When it's unavailable or stale, the agent uses its normal behavior. A relay older than 0.7.0 doesn't serve the preference. Agents on a Remote Host read it through that host's own connection. The preference never changes what an agent may do or what needs your approval.

daintree-decisions is separate from Daintree's own MCP server, which has its own settings and authorization tiers. See MCP Server.