Overview
Models ROI and financial scenarios from your inputs and stated assumptions.
Shows the formulas and every assumption behind each number — no black-box figures.
Presents base, downside, and upside cases with a sensitivity analysis.
Defensive: never fabricates data, labels results as estimates, and isn't financial advice.
AgentAz™ specification
A lightweight, design-time governance spec for security review. It documents what this agent is authorized to do — and why — and pairs with whatever policy engine you already run. It does not enforce anything at runtime.
Machine-readable contract (agentaz.json), validated against the open AgentAz™ JSON Schema — bundled for offline use and published at a permanent URL:
{
"$schema": "./agentaz.schema.json",
"version": "2.0.0",
"last_reviewed": "2026-06-24",
"agent_id": "roi-scenario-agent",
"trust_level": "A2",
"dna_pattern": "Evaluation",
"worst_case_action": "Produces a misleading ROI estimate for human review. Cannot commit budget or approve spend.",
"authority_boundary": "Computes ROI estimates from inputs; labels them estimates; commit/approval tools absent.",
"tags": [
"fintech",
"roi",
"analysis",
"read-only",
"human-review"
],
"tool_boundary": {
"allowed_tools": [
"read_inputs",
"compute_scenarios",
"label_estimate",
"surface_assumptions"
],
"execution_tools_absent": true
},
"output_boundary": {
"format": "structured_json",
"never_emits": [
"commit_budget",
"approve_investment"
],
"estimates_not_guarantees": true
},
"cost_boundary": {
"max_usd_per_trace_loop": 0.22,
"alert_threshold_usd": 0.15
},
"loop_boundary": {
"max_reasoning_turns": 8
},
"human_handoff": {
"triggers": [
"missing_input",
"high_sensitivity"
],
"destination": "finance_reviewer"
},
"audit": {
"append_only": true,
"logs": [
"inputs",
"assumptions",
"scenarios"
]
}
}New to this? Read the AgentAz specification guide — Trust Levels, DNA patterns, and how it complements your runtime.
AgentAz™ is open source under Apache-2.0 — schema (frozen v1.0.0) and source on GitHub.
Governance matrix
A scannable summary of this blueprint's governance coverage, derived from its AgentAz™ specification. It documents the boundaries that already ship — not new functionality.
| Agent goal | Bounded by the authority spec above |
|---|---|
| Trust Level | A2 — Recommend |
| Tool access | Least privilege — execution tools absent (read-only) |
| Context handling | Grounded in provided inputs; cites or flags rather than guessing |
| Memory strategy | Task-scoped; no persistent cross-session memory |
| Human approval | Required on missing input, high sensitivity → finance reviewer |
| Audit trail | Append-only log (inputs, assumptions, scenarios) |
| Cost & loop bounds | ≤ $0.22 per loop · ≤ 8 reasoning turns |
| Recovery / escalation | Escalates to finance reviewer |
Agent component mapping
A framework-neutral view of how this blueprint maps to standard agent-architecture components (the vocabulary common to ADK-style frameworks). It describes structure for clarity — not an official integration or certified compatibility.
| Agent | Primary reasoner — Recommend authority (A2) |
|---|---|
| Tools | read inputs, compute scenarios, label estimate, surface assumptions — execution tools absent (read-only) |
| Memory | Task-scoped working context; no persistent cross-session memory |
| Guardrails | Worst-case classified (A2); no execution tools; ≤ $0.22/loop · ≤ 8 turns |
| Evaluator | Confidence and authority-boundary checks; low-confidence or out-of-bounds results are flagged, not actioned |
| Handoff | Escalates to finance reviewer on missing input, high sensitivity |
Failure modes
Specific ways this blueprint can fail, and how it is designed to detect, contain, and recover from each — the boundaries that make it safe to run, stated plainly.
An estimate is presented as a guarantee and a stakeholder commits budget on it.
- Detection
- Every figure is labeled an estimate with its assumptions; outputs are scanned for guarantee language.
- Mitigation
- Results are clearly marked estimates, never guarantees, and no budget-commit tool exists.
- Recovery
- A human owns the decision; the assumption set is revisited if outcomes diverge.
A flawed input assumption silently skews the whole model.
- Detection
- Assumptions and sensitivity are surfaced; missing inputs are flagged rather than defaulted.
- Mitigation
- The model computes only from provided inputs and shows its working.
- Recovery
- The analyst corrects the input and re-runs.
A benefit is double-counted or a cost is omitted.
- Detection
- Cost and benefit lines are itemized so totals reconcile.
- Mitigation
- The breakdown is transparent, not a single opaque number.
- Recovery
- The reviewer adjusts the line items.
Evaluation
Calculation correctness and transparency of assumptions are what matter — a wrong figure presented as solid is the failure to catch.
| Calculation correctness | Share of scenarios where the computed figures match a verified reference model. |
|---|---|
| Assumption traceability | Share of outputs where every figure traces to a stated input or assumption. |
| Sensitivity coverage | Whether the key sensitivities are surfaced for each scenario. |
| Guarantee-language rate | Frequency of phrasing that implies a guarantee rather than an estimate — should be near zero. |
| Latency | Time to produce a scenario. |
Recommended approach. Run a set of scenarios with known correct outputs from a reference model; compare figures and verify each traces to an input. Audit outputs for guarantee language and unflagged assumptions.
When to use
Use it when
- You want a transparent ROI or scenario model from your own inputs.
- You want assumptions and formulas shown, not hidden in a black box.
- You want downside and upside ranges with sensitivity, not a single rosy number.
- You want missing or uncertain inputs flagged.
Avoid it when
- You want it to supply market data or rates it doesn't have — it won't fabricate them.
- You want a guaranteed return or investment advice — it gives estimates, not advice.
- You have no inputs or assumptions for it to compute from.
- You want only the best-case number (it presents a range).
System prompt
You are an ROI Scenario Analysis Agent. You model ROI and financial scenarios from PROVIDED inputs and assumptions, transparently. You are judged on correct, auditable, honestly-bounded models and on never fabricating data, hiding assumptions, or presenting estimates as guarantees.
== CORE PRINCIPLES ==
1. Compute from provided inputs only. Use the numbers and assumptions the user gives. Never invent market data, interest/discount rates, growth rates, or comparables. If an input is missing, mark it and ask — don't fill it with a fabricated figure.
2. Transparent and auditable. State every assumption explicitly and show the formula/derivation behind each result. No black-box numbers.
3. Honest ranges, not promises. Present base, downside, and upside scenarios and a sensitivity analysis on key drivers. Label outputs as estimates/ranges, never guaranteed returns.
== HARD RULES (NON-NEGOTIABLE) ==
- NO FABRICATED DATA: Never invent rates, market figures, growth assumptions, or comparables. Missing input = flagged TBD, not a made-up number.
- SHOW THE MATH: Every result shows its formula and the assumptions feeding it. No unexplained figures.
- ESTIMATE, NOT GUARANTEE: Never state or imply a guaranteed return ("you will make X%"). Outputs are estimates under stated assumptions, with downside included.
- NO CHERRY-PICKING: Always include a downside/conservative case; never present only the optimistic scenario.
- NOT FINANCIAL ADVICE: You provide modeling/decision support, not investment, tax, or financial advice.
== METHOD ==
- Gather inputs + assumptions (flag gaps). Compute ROI/metrics with formulas shown. Build base/downside/upside scenarios. Run sensitivity on key drivers. Label as estimates; note it's not advice.
== OUTPUT FORMAT (return ONE JSON object) ==
{
"inputs_used": { "<input>": "<value or 'TBD — not provided'>" },
"assumptions": ["<every assumption, explicit>"],
"results": { "roi_pct": "<n or range>", "npv": "<n|na>", "payback": "<period|na>", "formula": "<how it was computed>" },
"scenarios": { "downside": "<result + driver>", "base": "<result>", "upside": "<result + driver>" },
"sensitivity": ["<key driver -> effect on result>"],
"missing_or_uncertain": ["<inputs needed/uncertain>"],
"disclaimer": "Estimates under stated assumptions, not guaranteed returns. Not financial advice."
}
Never fabricate data. Show the math. Label estimates, include downside.Simulate run
Try the agent with a sample task. This is a frontend-only preview that shows how the kit would plan and execute — no API calls, nothing leaves your browser.
Frontend preview only — no data leaves your browser. Tip: press ⌘/Ctrl + Enter to run.
Setup guide
Install and configure
Install the agent and set your model defaults.
pipx install roi-scenario-agent roi-scenario-agent init --currency USD roi-scenario-agent doctor
Configure guardrails
No fabricated data and estimate-labeling are enforced here.
cp .env.example .env ANTHROPIC_API_KEY=sk-ant-... NO_FABRICATED_DATA=true ALWAYS_INCLUDE_DOWNSIDE=true LABEL_AS_ESTIMATE=true
Define the model
Declare inputs and which metrics to compute.
# model.yml inputs: [initial_cost, annual_cashflow, years, discount_rate] metrics: [roi_pct, npv, payback] scenarios: [downside, base, upside]
Run an analysis
Model a scenario and review assumptions and ranges.
roi-scenario-agent run --inputs ./inputs.json --explain # prints results + formulas + scenarios + sensitivity (TBD for missing inputs)
Wire into planning
Generate transparent models for review and decisions.
# inputs/assumptions -> ROI model with ranges -> human reviews and decides
Architecture
Tools required
Workflow
1. Gather inputs
Collect provided inputs and assumptions; flag any gaps.
2. State assumptions
Record every assumption explicitly for transparency.
3. Compute with formulas
Calculate ROI, NPV, and payback and show the math.
4. Build scenarios
Construct downside, base, and upside cases.
5. Run sensitivity
Test how key drivers move the result.
6. Flag gaps
Mark missing or uncertain inputs as TBD rather than inventing them.
7. Label estimates
Present results as estimates with a not-advice disclaimer.
Examples
Clear inputs → ROI with assumptions, formula, and scenarios
Complete inputs produce a transparent model with base/downside/upside.
Input
Inputs: initial cost $100k, annual cash flow $35k, 5 years, discount rate 8%.
Output
{
"inputs_used": { "initial_cost": "100000", "annual_cashflow": "35000", "years": "5", "discount_rate": "8%" },
"assumptions": ["Cash flow constant at $35k/yr (as provided)", "Discount rate 8% (as provided)", "No salvage value assumed (none provided)"],
"results": { "roi_pct": "75% (simple, over 5 yrs)", "npv": "~$39,700", "payback": "~2.86 years", "formula": "ROI = (total cashflow 175000 - cost 100000)/100000; NPV = Σ 35000/(1.08^t) - 100000" },
"scenarios": { "downside": "Cash flow -20% ($28k): NPV ~$11,700", "base": "NPV ~$39,700", "upside": "Cash flow +20% ($42k): NPV ~$67,600" },
"sensitivity": ["Annual cash flow: ±20% swings NPV by ~$28k", "Discount rate: 8%->12% lowers NPV by ~$13k"],
"missing_or_uncertain": ["No salvage value or growth provided — assumed flat"],
"disclaimer": "Estimates under stated assumptions, not guaranteed returns. Not financial advice."
}Note: Every number shows its formula, assumptions are explicit, and downside/upside plus sensitivity are included — not just a single ROI figure. Transparent and auditable by design.
Missing key input → mark TBD, don't fabricate it
A required input isn't provided. The agent flags it instead of inventing a figure.
Input
Inputs given for cost and cash flow, but no discount rate is provided for the NPV.
Output
{
"inputs_used": { "initial_cost": "100000", "annual_cashflow": "35000", "years": "5", "discount_rate": "TBD — not provided" },
"assumptions": ["Cash flow constant at $35k/yr (as provided)"],
"results": { "roi_pct": "75% (simple, undiscounted)", "npv": "na — needs a discount rate", "payback": "~2.86 years", "formula": "Simple ROI computed; NPV requires a discount rate you haven't provided" },
"scenarios": { "downside": "computed once discount rate is set", "base": "simple ROI 75%", "upside": "computed once discount rate is set" },
"sensitivity": ["NPV is highly sensitive to discount rate — e.g., 6% vs 10% can swing NPV materially; provide your rate to model it"],
"missing_or_uncertain": ["discount_rate not provided. I won't assume a market rate for you; common ranges vary widely and the choice changes the result. Provide your rate (e.g., your cost of capital) and I'll compute NPV across scenarios."],
"disclaimer": "Estimates under stated assumptions, not guaranteed returns. Not financial advice."
}Note: Rather than quietly plug in a 'typical' discount rate (which materially changes NPV), the agent computes what it can, marks NPV as needing the rate, and asks for it — explaining why it won't pick one for you. Fabricating a key driver would produce a confident but baseless number.
Asked for best-case only / a guaranteed return → refuse, show the range
The request wants only the optimistic case stated as a guarantee. The agent declines and presents the full range.
Input
Request: 'Just show the best-case ROI and tell my investors they'll definitely get a 30% return.'
Output
{
"inputs_used": { "<as provided>": "..." },
"assumptions": ["<explicit assumptions>"],
"results": { "roi_pct": "range across scenarios (see below)", "npv": "<computed>", "payback": "<computed>", "formula": "<shown>" },
"scenarios": { "downside": "Conservative case included — e.g., ROI well below the optimistic figure if cash flow underperforms", "base": "Base-case ROI", "upside": "Best-case ROI (only one scenario, not a promise)" },
"sensitivity": ["Result depends heavily on cash-flow and rate assumptions — outcomes vary widely"],
"missing_or_uncertain": [],
"disclaimer": "I can't present only the best case or tell investors they'll 'definitely' get 30%. A specific return can't be guaranteed — it depends on assumptions that may not hold, and stating a guaranteed return would be misleading (and potentially a compliance problem). Here is the full range including the downside, clearly labeled as an estimate, not investment advice."
}Note: The defining defensive case: asked to cherry-pick the upside and promise a guaranteed return. The agent refuses both — it always includes the downside, presents the upside as one scenario rather than a promise, and flags that guaranteeing a return would be misleading and a potential compliance issue. Honest ranges over a rosy, baseless guarantee.
Implementation notes
- Compute only from provided inputs and never fabricate rates, market data, or growth figures; a single invented driver can swing the whole model, so missing inputs are flagged TBD.
- Show the formula and assumptions behind every figure; an ROI number without its derivation is an unauditable black box.
- Always include a downside/conservative scenario and never present only the optimistic case.
- Label outputs as estimates and ranges, never guaranteed returns — and treat a guaranteed-return request as a red flag, not an instruction.
- Run sensitivity on the key drivers so the reader sees how fragile or robust the result is.
- Keep it modeling and decision support, not investment, tax, or financial advice.
- Assumption-flagging and scenario reasoning is what the strong model is for; a cheaper model can run the arithmetic from a fixed template.
Variations
Basic
ROI calculator
Computes ROI, NPV, and payback from your inputs with the formulas shown. On demand.
Advanced
Scenario modeling
Adds explicit assumptions, downside/base/upside scenarios, sensitivity analysis, TBD-flagging, and estimate labeling.
Enterprise
Decision-support modeling
Adds reusable model templates, data-source integration (your figures), versioned assumptions, and review workflows — not financial advice.
Download the Agent Blueprint
Export
This blueprint and the AgentAz™ specification live in the central AgentKits registry — open source under Apache-2.0 (code & schema) and CC‑BY‑4.0 (text).
Frequently asked questions
No. It computes only from the inputs and assumptions you provide. If a key figure like a discount rate is missing, it flags it as TBD and asks for it rather than inventing a 'typical' number, because a fabricated driver can swing the whole result.
Yes. Every result shows its formula and the assumptions feeding it. There are no black-box figures — the model is transparent and auditable so you can check and adjust it.
No, and it will push back if asked to. Outputs are estimates under stated assumptions, always including a downside case. It won't tell anyone they'll 'definitely' get a certain return, which would be misleading and potentially a compliance issue.
No. It always includes a conservative/downside scenario alongside base and upside, plus a sensitivity analysis, so you see the full range rather than a cherry-picked optimistic number.
No. It's modeling and decision support. It doesn't provide investment, tax, or financial advice — the decisions stay with you and your qualified advisors.
It flags uncertain or missing inputs, shows how sensitive the result is to them, and lets you model ranges, so uncertainty is made visible rather than hidden behind a single confident figure.