Building it on every surface

The step is the same everywhere: one parameter, questions, holds the questions document, and the output ports follow from it. The editor, the API, the MCP server and the agent all validate it with the same rules and the same messages.

In the editor

Add Decide with a Model from AI › Analysis. Its panel has:

• Questions — one card per question, with Add to create one (up to 16). On each card: the name (it becomes the ports: the card shows them, Ports: route, route_probability); the type — Yes / No, Choice or Score; the instructions, with a placeholder that reminds you a yes/no is a statement; the threshold; and for a choice the options, for a score the levels lowest first, each with an optional description of what it means. A name that is invalid, reserved or used twice is shown in red with the reason.
• On Uncertain — mark, skip_branch, fail, each described.
• Image Detail — low or high.
• Image Set Limit and Label Images, under the advanced settings, for an image set.

The node shows its two fixed outputs, Decision and All Accepted, and two outputs per question, as soon as the question is written. Connect from them as from any other port. Renaming a question renames its ports and removes the connections that left from the old names; changing a question’s type removes the connections whose type changed.

In a workflow definition (REST API v1)

The node in a definition (POST /api/v1/workflows, PUT /api/v1/workflows/{id}/definition):

{
  "id": "triage",
  "type": "ai/decide",
  "label": "Triage the message",
  "parameters": {
    "questions": {
      "schema": "madoo.decision-questions/v1",
      "questions": [
        { "name": "route", "type": "choice", "instructions": "Which team should handle this message?", "threshold": 0.7,
          "options": [ { "value": "refund", "description": "The customer asks for money back" },
                      { "value": "shipping", "description": "Delivery, tracking, address or courier" },
                      { "value": "other", "description": "Anything else" } ] },
        { "name": "damaged", "type": "yes_no", "instructions": "The item the customer received is damaged or broken." }
      ]
    },
    "on_uncertain": "mark"
  }
}

and its connections use the ports the questions give:

[ { "from_node": "message", "from_output": "text", "to_node": "triage", "to_input": "content" },
  { "from_node": "triage", "from_output": "route", "to_node": "pick_reply", "to_input": "selector" },
  { "from_node": "triage", "from_output": "all_accepted", "to_node": "only_sure", "to_input": "condition" } ]

• The schema of the parameter is GET /api/v1/json-schemas/madoo.decision-questions/v1; the schema of the decision output is GET /api/v1/json-schemas/madoo.decision/v1.
• GET /api/v1/node-types/ai/decide describes the node, and its dynamic ports as derivation: "decision_questions": two output ports per question, named after it (see the catalogue).
• Every create, update and publish checks the questions, and so does POST /api/v1/workflows/{id}/validate with a candidate definition: a problem is a blocking issue with a code, the message and a path — “Name ‘Bad Name’ must start with a lowercase letter…”, invalid_port_name at $.nodes[1].parameters.questions.questions[0].name — and a create or update answers 422. The codes are listed in Troubleshooting.
• POST /api/v1/workflows/{id}/estimate gives the step’s cost as an estimate from tokens, with what it assumed.

After a run, GET /api/v1/executions/{id}/result gives each output: a question’s port is a boolean, a text or a number; the decision output is the whole madoo.decision/v1 document.

Through the MCP server

An assistant connected to Madoo’s MCP server builds the step with the usual tools:

1. search_node_types with “decide”, “yes no question” or “classify” finds ai/decide; get_node_type gives its ports, parameters and the shape of questions.
2. get_json_schema with madoo.decision-questions/v1 gives the exact schema of the questions.
3. create_workflow_draft / update_workflow_draft with the node and its connections, then validate_workflow until it is valid — each issue has a path and a suggestion.
4. estimate_execution, publish_workflow, execute_workflow, and get_execution_result to read the answers.

Ask it in plain words: “Add a step that checks each product photo for focus, exposure and a watermark, and only resizes the ones that pass; send the others to a review list.”

With the AI agent and the AI assistant

Madoo’s AI agent and AI assistant know the step from the same catalogue and guidance: they choose it when a workflow must judge content, write the questions in the right shape, and route on the answers with Filter, Predicate or Select by Key. Say what must be judged and what happens next — “if the message is a refund request and you are sure, draft a reply; otherwise send it to a person” — and let them write the questions; review the instructions and thresholds they chose, as you would a colleague’s.

Rules every surface applies

• Values in options are identifiers: the steps downstream compare them exactly (Predicate equals, Select by Key with caseSensitive: true).
• The question’s name is the port’s name: keep it stable once other steps are connected to it.
• Run inputs that fill content are text: an execution input is JSON-encoded ("\"The parcel is late\""), as for every text input.