> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/mcp-tools/decisions.md). # Decision tools These tools cover Algenta's decisioning lane over MCP: run Monte Carlo simulations, rank options, score and compare scenarios, drive the simplified product helpers, and persist decisions to decision memory so you can close the loop by recording what actually happened. Each tool wraps a single authenticated endpoint under `/v1`. Configure `algenta-mcp` first — see [MCP server](/sdks/mcp.md). For the modeling background, see [Simulation models & distributions](/concepts/simulation-models.md) and [Decision memory](/concepts/decision-memory.md). {% hint style="info" %} Two altitudes are available. `simulate`, `recommend`, `score`, `batch`, and `compare` give you full Monte Carlo control; the `product_*` helpers are one-shot, minimal-setup wrappers for common product jobs. `plan_decision` returns just the structured plan without the full envelope. {% endhint %} ## Simulate and recommend | Tool | What it does | Key inputs | | --------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `simulate` | Run a Monte Carlo simulation and return a structured recommendation. | `variables` (required; each `name`, `low`, `high`, optional `mode`); `mode` (`auto`\|`expert`), `objective` (`maximize`\|`minimize`\|`maximize_net_value`), `n_simulations` (default 10000) | | `recommend` | Compare named options and return a ranked recommendation. | `actions` (required; min 2; `name`, `variables`, `objective`); `n_simulations` | | `score` | Score one simulation request with explicit weights, returning the envelope plus a score breakdown. | `request` (required); `scoring_weights` | | `batch` | Run multiple simulation requests in one call with per-item success/failure. | `items` (required; min 1) | | `compare` | Run named scenarios side by side and return the winner plus deltas vs. the best. | `scenarios` (required; min 2; `name`, `request`); `runs`, `seed` | | `plan_decision` | Build a structured DecisionPlan from a simulation-style request, without the full envelope. | simulation-style payload | ## Product helpers | Tool | What it does | Key inputs | | ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `product_decision` | Run the decision helper and return the chosen action plus a risk summary. | `inputs` (required; `value` + optional `low`/`high`); `objective`, `risk_tolerance`, `scenarios`, `engine`, `label` | | `product_agent_run` | Run the task-execution helper and return a compact task result. | `task` (required); `context`, `tools`, `max_steps`, `output_format` | | `product_optimize` | Run the optimization helper and return the best variable values. | `objective`, `variables` (required); `constraints`, `iterations`, `engine` | | `product_retrieve` | Run the retrieval helper over caller-supplied documents or a `collection_id`. | `query` (required); `documents`, `collection_id`, `top_k`, `rerank` | | `product_forecast` | Run the forecast helper over a historical metric series. | `metric`, `history` (required); `horizon`, `seasonality`, `confidence_level` | ## Decision memory | Tool | What it does | Key inputs | | ------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `log_decision` | Persist one decision to the audit trail (immutably hashed). | `chosen_action` (required); `run_id`, `context`, `options_considered`, `expected_value`, `confidence`, `rationale`, `risk_p5`, `risk_p95`, `risk_pol`, `request_hash`, `result_hash` | | `list_decisions` | Retrieve the audit trail, most recent first. | `page`, `limit`, `page_size`, `with_outcome_only` | | `get_decision` | Fetch one record by id. | `decision_id` (required) | | `record_outcome` | Record what actually happened; computes `outcome_delta = actual − expected`. | `decision_id`, `actual_outcome` (required); `outcome_notes` | | `execute_decision` | Dispatch a logged decision to an external webhook and persist the receipt. | `decision_id`, `webhook_url` (required); `timeout_seconds`, `force`, `override_safety`, `metadata` | | `delete_decision` | Delete one record by id. | `decision_id` (required) | ## Endpoint mapping | Tool | Method | Endpoint | | ------------------- | -------- | ------------------------------------- | | `simulate` | `POST` | `/v1/simulate` | | `recommend` | `POST` | `/v1/recommend` | | `score` | `POST` | `/v1/score` | | `batch` | `POST` | `/v1/batch` | | `compare` | `POST` | `/v1/compare` | | `plan_decision` | `POST` | `/v1/decisions/plan` | | `product_decision` | `POST` | `/v1/decision` | | `product_agent_run` | `POST` | `/v1/agent/run` | | `product_optimize` | `POST` | `/v1/optimize` | | `product_retrieve` | `POST` | `/v1/retrieve` | | `product_forecast` | `POST` | `/v1/forecast` | | `log_decision` | `POST` | `/v1/decisions` | | `list_decisions` | `GET` | `/v1/decisions` | | `get_decision` | `GET` | `/v1/decisions/{decision_id}` | | `record_outcome` | `PATCH` | `/v1/decisions/{decision_id}/outcome` | | `execute_decision` | `POST` | `/v1/decisions/{decision_id}/execute` | | `delete_decision` | `DELETE` | `/v1/decisions/{decision_id}` | ## Worked examples ### Run a Monte Carlo simulation In `auto` mode, `simulate` needs only your `variables` (each a triangular range) and an objective. It returns a recommended action, confidence, and downside/upside percentiles. {% code title="simulate (tool call)" %} ```json { "name": "simulate", "arguments": { "mode": "auto", "objective": "maximize_net_value", "n_simulations": 10000, "variables": [ { "name": "revenue", "low": 80000, "high": 200000 }, { "name": "cost", "low": 40000, "high": 90000 } ] } } ``` {% endcode %} ```bash curl -sS "$ALGENTA_BASE_URL/v1/simulate" \ -H "Authorization: Bearer $ALGENTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "auto", "n_simulations": 10000, "scenario": { "variables": { "revenue": { "low": 80000, "high": 200000 } }, "objective": "maximize_net_value" } }' ``` ### Forecast a metric with the product helper `product_forecast` takes a metric name and a history series and projects it forward. {% code title="product\_forecast (tool call)" %} ```json { "name": "product_forecast", "arguments": { "metric": "mrr", "history": [100, 110, 121, 133], "horizon": 3, "confidence_level": 0.9 } } ``` {% endcode %} ### Log a decision, then close the loop Persist the chosen action to decision memory, then record the real outcome later. `record_outcome` reports `outcome_delta` so you can measure prediction accuracy over time. {% code title="log\_decision (tool call)" %} ```json { "name": "log_decision", "arguments": { "chosen_action": "Launch in EU first", "context": "Q3 go-to-market sequencing", "options_considered": ["Launch in EU first", "Launch in US first"], "expected_value": 145000, "confidence": 0.72, "run_id": "$RUN_ID" } } ``` {% endcode %} {% code title="record\_outcome (tool call)" %} ```json { "name": "record_outcome", "arguments": { "decision_id": "$DECISION_ID", "actual_outcome": 138500, "outcome_notes": "Slightly below plan; slower onboarding than modeled." } } ``` {% endcode %} ```bash curl -sS -X PATCH "$ALGENTA_BASE_URL/v1/decisions/$DECISION_ID/outcome" \ -H "Authorization: Bearer $ALGENTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "actual_outcome": 138500 }' ``` {% hint style="warning" %} `execute_decision` dispatches to an external webhook and honors confidence and risk-floor policy gates. `override_safety` bypasses those gates and `force` overrides the idempotency guard — use both only when you understand the consequences. {% endhint %} ## Related pages {% content-ref url="/pages/ktXIojcv61EsP0IhlJTb" %} [Decision memory](/concepts/decision-memory.md) {% endcontent-ref %} {% content-ref url="/pages/eDDxcUfD56Kbb5TWZoYP" %} [Run a decision](/guides/run-a-decision.md) {% endcontent-ref %} {% content-ref url="/pages/dbMexAzWYilfd77tn3O8" %} [API endpoint reference](/http-api/reference.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.algenta.ai/mcp-tools/decisions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.