Servers Playground How we check Add a server Log in

Worthune Verified Financial Models

Working · 3.1 s

com.worthune/modelsv1.8.0 Domain verified

61 verified financial models and a household planning engine: 20 MCP tools, 6 keyless, specs cited.

Finance & Payments

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://worthune.com/api/mcp/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

answer_question

Answer one open question. value proposes the corrected field as a data-change proposal that an approver or owner must approve before anything is written; confirm: true records that the data is right, and the same check will not ask about the field again. Send exactly one of them. Developer, approver or owner key. Refused when the household changed since the question was asked. Same as POST /api/v1/questions/{id}/answer.

question_idinteger, required

notestring

valuestring

api_keystring

Worthune API key (wk_…)

confirmboolean

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Worthune Verified Financial Models MCP server | mcptry

Tools (30)

answer_question

Argument	Type	Description
note	string
value	any
api_key	string	Worthune API key (wk_…)
confirm	boolean
question_id*	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "question_id"
  ],
  "properties": {
    "note": {
      "type": "string",
      "maxLength": 500
    },
    "value": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ]
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "confirm": {
      "type": "boolean",
      "const": true
    },
    "question_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

archive_household

Archive a stored household (never deleted: the row stays readable, leaves the active-household meter, and stops accepting writes or projections). The same operation as DELETE /api/v1/households/{id}.

destructive

Argument	Type	Description
id*	integer
api_key	string	Worthune API key (wk_…)

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    }
  }
}

create_household

Create a persistent household resource from a household-schema document (docs/household-schema-spec.md: members, accounts by tax wrapper, liabilities, income and expense streams). Validation rejects with JSON-path errors — fix the payload in one pass. Returns the household id to use with get/replace/project_household.

Argument	Type	Description
label	string	Your own name for the household
api_key	string	Worthune API key (wk_…)
household*	object	Household-schema document
importKey	string	Your own stable id for this household: a retry with the same importKey returns the household already created, never a twin (same contract as POST /api/v1/households).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "household"
  ],
  "properties": {
    "label": {
      "type": "string",
      "description": "Your own name for the household"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "household": {
      "type": "object",
      "description": "Household-schema document",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "importKey": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{1,128}$",
      "description": "Your own stable id for this household: a retry with the same importKey returns the household already created, never a twin (same contract as POST /api/v1/households)."
    }
  }
}

create_mandate

Assign a standing mandate: strategy-watch (one household, the strategies you choose), tax-optimization (one household, minimize-lifetime-tax, the tax strategies) or rules-change (the whole book, Growth and above: when tax rules or your assumption profile change, finds and ranks every affected household; send no household_id). Each has an objective, pinned constraints and an approval policy. Lodestar then works it when a deadline approaches, the household changes, rules or the organization's assumption profile change, a scheduled review comes due, or on run_mandate, and files proposals for an approver. constraints needs horizonYears and exactly one of profile { id, version } or assumptions { … } (never an implicit default); optional: strategies, materialityFloorUsd (default 1000), cooldownDays (30), maxOpenProposals (3), reviewCadence (quarterly), planner ("on"/"off", default off: the organization's certified planner model chooses among gate-passed proposals), taxRates, ladderCandidates, illustrativeCharacteristics, bracketFill { fillToRatesPct?, years? }, charitableGiving { annualGivingUsd, … } (tax-optimization runs charitable-giving only when charitableGiving names the gifts). One mandate per type per household. Each cycle's sweep counts the household as active for the month. Developer or owner key. Same as POST /api/v1/mandates.

Argument	Type	Description
type	string	Default strategy-watch
status	string	Default active
api_key	string	Worthune API key (wk_…)
objective*	object
constraints*	object

decide_household

Run a Household Coordination Engine strategy on a stored household and get back a ranked decision object with evidence records. Strategies: withdrawal-sequencing (no params); roth-ladder (params.candidates: [{annualAmountUsd, years}]); ss-claiming (params.candidateAges?: {memberId: [ages 62-70]}); asset-location (params.taxRates: {marginalOrdinary, qualifiedAndLtcg} plus params.characteristics or params.illustrativeCharacteristics: true — the illustrative set is labeled not-a-recommendation and is never applied silently); tax-loss-harvesting (params.ordinaryMarginalRatePct, optional longTermRatePct and realizedGains); annual-gifting (params.doneeCount, params.years); pension-election (params.ownerId, startAge, discountRatePct, options — EPVs from the NCHS life table; adults need sex); bracket-fill (params.fillToRatesPct?: [10|12|22|24|32|35], params.years? — Roth conversions sized each year to the top of the bracket); charitable-giving (params.annualGivingUsd, optional otherItemizedDeductionsUsd, bunchYears 2-5, iraDistributionsUsd — every year vs bunched vs QCD routes under the 2026 charitable rules). Alternatives are ranked best-first by a checkable score under a named objective; deltas name their baseline; every projection-backed candidate links its own verifiable record; exclusions are stated in the notes.

Argument	Type	Description
id*	integer
params	object	Strategy-specific parameters (see the tool description)
api_key	string	Worthune API key (wk_…)
horizon*	object
profile	object

draft_import_mapping

WS3.5c: AI drafts the mapping; determinism executes it. Send up to 10 sample records from an export (column → string cell) and get back a DRAFT mapping template for import_households' template + records path. Three deterministic gates run before anything returns: strict JSON, the transcription guard (a numeric const anywhere in the draft is rejected — numbers bind to columns, never to values a model wrote), and the real import dry-run over your sample. Nothing is written. Review the template and the unmappedColumns honesty list, then run import_households yourself with dryRun: true over the full export.

read-only

Argument	Type	Description
notes	string	Context for the draft (what the export is, quirks)
api_key	string	Worthune API key (wk_…)
sampleRecords*	array	1-10 sample records, column → string cell

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "sampleRecords"
  ],
  "properties": {
    "notes": {
      "type": "string",
      "description": "Context for the draft (what the export is, quirks)"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "sampleRecords": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "1-10 sample records, column → string cell"
    }
  }
}

get_decision

One stored decision in full: the decision object as it was produced, the household version it ran against, and its evidence record with the hashed inputs — enough to re-verify it with /api/v1/records/verify or the SDKs' verifyRecord. Decisions stored before their inputs were retained are returned hash-only and say so. Same as GET /api/v1/decisions/{id}.

read-only

Argument	Type	Description
api_key	string	Worthune API key (wk_…)
decision_id*	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "decision_id"
  ],
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "decision_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

get_household

Fetch a stored household document and its metadata by id.

read-only

Argument	Type	Description
id*	integer	Household id from create_household
api_key	string	Worthune API key (wk_…)

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Household id from create_household",
      "exclusiveMinimum": 0
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    }
  }
}

get_household_picture

One household, one picture: the balance sheet by wrapper and owner, income and spending this year, how current the last computation is against the engine's spec (the same drift reasons the weekly scan delivers), the newest decisions, and a data-quality report naming what is missing and what supplying it would unlock. Sums only — no new number of consequence; nothing is stored. Same as GET /api/v1/households/{id}/picture. Pass as_of (YYYY-MM-DD) to pin the date; it is echoed back.

read-only

Argument	Type	Description
id*	integer
as_of	string	YYYY-MM-DD or ISO timestamp; default now
api_key	string	Worthune API key (wk_…)

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD or ISO timestamp; default now"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    }
  }
}

get_ledger

Ledger entries written by approvals, newest first, optionally for one mandate or household, with the total. Each is an evidence record (hash over its inputs and outputs, Ed25519-signed with the key at /api/v1/records/keys) naming the stored decision it came from. Values are PROJECTED and NOMINAL against each decision's own baseline; the total is a sum of projections, not realized value. Any key role. Same as GET /api/v1/ledger.

read-only

Argument	Type	Description
api_key	string	Worthune API key (wk_…)
mandate_id	integer
household_id	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "mandate_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "household_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

get_mandate

One mandate and its last 20 cycles, each with the strategies swept and the gate's reason for every candidate it did not propose (below the floor, cooldown, duplicate, max open), so 'why did nothing happen?' has an answer. Any key role. Same as GET /api/v1/mandates/{id}.

read-only

Argument	Type	Description
api_key	string	Worthune API key (wk_…)
mandate_id*	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "mandate_id"
  ],
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "mandate_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

get_model_contract

Get a model's machine-readable contract: required inputs with types and valid domains, cross-field constraints, sentinel-value meanings, and the government constants (with sources) the model uses. Set include_spec to also receive the full specification markdown (exact formulas, assumptions, exclusions, known issues).

read-only

Argument	Type	Description
model*	string	Model name from list_models, e.g. 'relocation'
api_key	string	Worthune API key (wk_…) — required for include_spec on non-sample models; or send it once as an Authorization: Bearer header.
include_spec	boolean	Also return the full spec markdown (default false). Public for the free-sample models; other models need api_key.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "model"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name from list_models, e.g. 'relocation'"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…) — required for include_spec on non-sample models; or send it once as an Authorization: Bearer header."
    },
    "include_spec": {
      "type": "boolean",
      "description": "Also return the full spec markdown (default false). Public for the free-sample models; other models need api_key."
    }
  }
}

import_households

Migrate a book (WS3.5): import up to 200 households in one call, with dryRun: true validating everything and writing NOTHING — iterate until the per-row, per-field report is clean, then run for real. Two shapes: households[] of { importKey, label?, household } documents, or template + records — a declarative mapping template (docs/data-migration.md) executed deterministically over raw exported records, so YOU draft the small reviewable template and the engine does the transcription. importKey is the caller's stable id: re-runs are idempotent (already-imported keys skip and report their householdId); imports never overwrite.

Argument	Type	Description
dryRun	boolean	Validate everything, write nothing
api_key	string	Worthune API key (wk_…)
records	array	Raw exported records, column → string cell
template	object	Mapping template (templateVersion 0.1.0) for the records path
households	array	Direct rows: { importKey, label?, household }

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "dryRun": {
      "type": "boolean",
      "description": "Validate everything, write nothing"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "Raw exported records, column → string cell"
    },
    "template": {
      "type": "object",
      "description": "Mapping template (templateVersion 0.1.0) for the records path",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "households": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Direct rows: { importKey, label?, household }"
    }
  }
}

list_decisions

The append-only history of coordination strategies run on a stored household, newest first — id, strategy, spec version, household version, record hash, when. Metadata only; get_decision returns one in full. Same as GET /api/v1/households/{id}/decisions.

read-only

Argument	Type	Description
id*	integer	Household id
api_key	string	Worthune API key (wk_…)

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Household id",
      "exclusiveMinimum": 0
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    }
  }
}

list_example_households

Twelve FICTIONAL households, each built to exercise a different part of the planning engine — accumulation, a Roth conversion window, drawdown on a low-basis portfolio, spousal Social Security coordination, running out of money, negative amortization, and more. Use one as a starting point for try_household_projection, or as a worked shape when helping someone describe their own household. Pass an id to get the full document back. No API key required.

read-only

Argument	Type	Description
id	string	An example id; omit to list all twelve with their summaries.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "id": {
      "type": "string",
      "description": "An example id; omit to list all twelve with their summaries."
    }
  }
}

list_households

List the organization's stored households — id, label, advisorRef, version, status, when it was last computed — without the documents (get_household returns one in full). Defaults to active households; GET /api/v1/households returns every status — pass status: "all" for the same listing.

read-only

Argument	Type	Description
status	string	Filter by status (default: active)
api_key	string	Worthune API key (wk_…)

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "status": {
      "enum": [
        "active",
        "archived",
        "all"
      ],
      "type": "string",
      "description": "Filter by status (default: active)"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    }
  }
}

list_mandates

The organization's mandates, newest first, optionally for one household or status, with an alert listing trigger events left open over an hour. Any key role. Same as GET /api/v1/mandates.

read-only

Argument	Type	Description
status	string
api_key	string	Worthune API key (wk_…)
household_id	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "status": {
      "enum": [
        "draft",
        "active",
        "paused",
        "ended"
      ],
      "type": "string"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "household_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

list_models

List Worthune's Concordance-tested financial calculation models (an independent second implementation must agree with the engine, per the published spec). Returns model names and spec versions. Call get_model_contract before running a model.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {}
}

list_proposals

Proposals Lodestar filed for a person to decide, newest first, optionally filtered by status (pending, approved, rejected, expired, superseded, stale, withdrawn), mandate or household. Each carries the recommendation and its intents verbatim from the decision, the projected value (NOMINAL horizon-end dollars against the current plan, not discounted, not realized) with its basis, the alternatives considered, caveats, and the evidence (stored decision id, record hash, signature). Any key role. Same as GET /api/v1/proposals.

read-only

Argument	Type	Description
status	string
api_key	string	Worthune API key (wk_…)
mandate_id	integer
household_id	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "status": {
      "enum": [
        "pending",
        "approved",
        "rejected",
        "expired",
        "superseded",
        "stale",
        "withdrawn"
      ],
      "type": "string"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "mandate_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "household_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

list_questions

Lodestar's questions about one field of a household's data (a taxable account with no cost basis, a Social Security stream with no amount, living expenses of zero), asked by deterministic checks in every household cycle; at most one open per mandate. Filter by status (open, answered, confirmed, stale), mandate_id or household_id. Any key role. Same as GET /api/v1/questions.

read-only

Argument	Type	Description
status	string
api_key	string	Worthune API key (wk_…)
mandate_id	integer
household_id	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "status": {
      "enum": [
        "open",
        "answered",
        "confirmed",
        "stale"
      ],
      "type": "string"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "mandate_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "household_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

manage_preferences

An advisor's standing preferences, which the gate enforces in every cycle: avoid-strategy (optionally until a date), min-value for a strategy, max-annual-conversion, avoid-alternative. action list (any role); add (an approver or owner key confirms it at once, a developer key only suggests it); confirm a suggestion (approver or owner); remove (a suggestion: developer and up; a confirmed preference: approver or owner). Same as /api/v1/mandates/{id}/preferences and /api/v1/preferences/{id}.

Argument	Type	Description
kind	string
note	string
until	string	YYYY-MM-DD, avoid-strategy only
action*	string
api_key	string	Worthune API key (wk_…)
strategy	string
amount_usd	number
mandate_id	integer	Required for list and add
preference_id	integer	Required for confirm and remove

narrate_decision

The Verified Narrative: client- or advisor-ready prose for a stored decision (decision_id) or an inline decision object. A model drafts the narrative FROM the decision; a deterministic gate then extracts every number in the draft and verifies each against the decision's own values — correctly-rounded restatements pass, invented numbers reject the draft whole (one retry, then refusal; a narrative is never patched). The response reports how many claims were checked.

read-only

Argument	Type	Description
api_key	string	Worthune API key (wk_…)
audience	string	Default "client"
decision	object	An inline decision object (validated first)
decision_id	integer	A stored decision's id (from decide_household)

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "audience": {
      "enum": [
        "client",
        "advisor"
      ],
      "type": "string",
      "description": "Default \"client\""
    },
    "decision": {
      "type": "object",
      "description": "An inline decision object (validated first)",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "decision_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "A stored decision's id (from decide_household)"
    }
  }
}

patch_household

Apply a collection-level delta to a stored household without resending the whole document: set scalars (filingStatus, state), upsert entries by id (replace or append), remove entries by id. expectedVersion (from get_household) is REQUIRED — a delta is only meaningful against a version you have read. The merged result is validated in full; a delta can never produce an invalid household.

Argument	Type	Description
id*	integer
set	object	Scalar fields: { filingStatus?, state? } (state: null clears it)
remove	object	Collection → ids to remove
upsert	object	Collection → entries with ids: replace matching ids, append new ones
api_key	string	Worthune API key (wk_…)
expectedVersion*	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id",
    "expectedVersion"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "set": {
      "type": "object",
      "description": "Scalar fields: { filingStatus?, state? } (state: null clears it)",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "remove": {
      "type": "object",
      "description": "Collection → ids to remove",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "upsert": {
      "type": "object",
      "description": "Collection → entries with ids: replace matching ids, append new ones",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        }
      }
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "expectedVersion": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

project_household

Run the deterministic multi-year projection on a stored household — income, RMDs, federal + covered state tax, expenses, amortization, cash flow, net worth per year — optionally with seeded Monte Carlo (same seed, same result). Assumptions: pass your own, pin a profile by id+version, or omit both for the labeled illustrative default; the response always names its assumptionsSource. Every simplification that fired is listed in projection.assumptionsApplied — show your work.

Argument	Type	Description
id*	integer
policy	object	Same shape as try_household_projection; applies to the deterministic run and every Monte Carlo path, and is hashed into the record.
api_key	string	Worthune API key (wk_…)
horizon*	object
profile	object
monteCarlo	object
assumptions	object

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id",
    "horizon"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "policy": {
      "type": "object",
      "properties": {
        "rothConversions": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "year",
              "amountUsd"
            ],
            "properties": {
              "year": {
                "type": "integer",
                "maximum": 9007199254740991,
                "minimum": -9007199254740991
              },
              "amountUsd": {
                "type": "number"
              }
            }
          }
        },
        "withdrawalOrder": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "description": "Same shape as try_household_projection; applies to the deterministic run and every Monte Carlo path, and is hashed into the record.",
      "additionalProperties": false
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "horizon": {
      "type": "object",
      "required": [
        "startYear",
        "years"
      ],
      "properties": {
        "years": {
          "type": "integer",
          "maximum": 80,
          "minimum": 1
        },
        "startYear": {
          "type": "integer",
          "maximum": 2150,
          "minimum": 1900
        }
      },
      "additionalProperties": false
    },
    "profile": {
      "type": "object",
      "required": [
        "id",
        "version"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      }
    },
    "monteCarlo": {
      "type": "object",
      "required": [
        "seed"
      ],
      "properties": {
        "seed": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        "longevity": {
          "type": "boolean"
        },
        "simulations": {
          "type": "integer",
          "maximum": 5000,
          "minimum": 10
        },
        "returnVolatility": {
          "type": "number",
          "maximum": 1,
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "assumptions": {
      "type": "object",
      "required": [
        "annualReturn",
        "inflationRate",
        "defaultIncomeGrowth"
      ],
      "properties": {
        "annualReturn": {
          "type": "number"
        },
        "inflationRate": {
          "type": "number"
        },
        "returnsByWrapper": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        },
        "socialSecurityCola": {
          "type": "number"
        },
        "defaultIncomeGrowth": {
          "type": "number"
        }
      },
      "additionalProperties": false
    }
  }
}

replace_household

Full-document replace with optimistic concurrency: pass expectedVersion (from get_household) and a stale write loses cleanly with the current version instead of clobbering a concurrent change.

Argument	Type	Description
id*	integer
label	any
api_key	string	Worthune API key (wk_…)
household*	object	Replacement household-schema document
expectedVersion	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id",
    "household"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "household": {
      "type": "object",
      "description": "Replacement household-schema document",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "expectedVersion": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

review_proposal

Decide one pending proposal. APPROVER OR OWNER KEY ONLY: developer and viewer keys are refused, so the key that configures mandates cannot sign off their output. approve executes nothing; it writes one signed projected-value ledger entry (a re-pin proposal moves the mandate to the newer profile version instead). reject needs a reason: not-material, client-preference, timing, data-is-wrong, already-done, or other (with a note). Refused when the proposal is not pending, has expired, or the household changed since it was computed. An agent should only call this when the person it acts for has made the decision. Same as POST /api/v1/proposals/{id}/approve and /reject.

Argument	Type	Description
note	string
reason	string
api_key	string	Worthune API key (wk_…)
decision*	string
proposal_id*	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "proposal_id",
    "decision"
  ],
  "properties": {
    "note": {
      "type": "string",
      "maxLength": 1000
    },
    "reason": {
      "enum": [
        "not-material",
        "client-preference",
        "timing",
        "data-is-wrong",
        "already-done",
        "other"
      ],
      "type": "string"
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "decision": {
      "enum": [
        "approve",
        "reject"
      ],
      "type": "string"
    },
    "proposal_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

run_mandate

Record a manual trigger and run the mandate's cycle now: sweep its strategies on the household's current version, store each decision, and file proposals that clear the gate. Returns the cycle; read proposals with list_proposals and the reasons with get_mandate. Developer or owner key. Same as POST /api/v1/mandates/{id}/run.

Argument	Type	Description
api_key	string	Worthune API key (wk_…)
mandate_id*	integer

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "mandate_id"
  ],
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "mandate_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    }
  }
}

run_model

Run a Concordance-tested calculation model. Inputs must satisfy the contract from get_model_contract (all fields required, values inside their domains — out-of-domain requests are rejected, never clamped). The response echoes inputs, spec version, assumptions, triggered sentinels, and sourced constants; outputs are exactly what the engine computed, untouched. Share the matching interactive calculator with users: https://worthune.com/scenarios/<model> for scenario models.

read-only

Argument	Type	Description
model*	string	Model name from list_models
inputs*	object	Model inputs per the contract's domains
api_key	string	Worthune Pro API key (wk_…). Required for models outside the free sample; the free models run without one.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "model",
    "inputs"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name from list_models"
    },
    "inputs": {
      "type": "object",
      "description": "Model inputs per the contract's domains",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "api_key": {
      "type": "string",
      "description": "Worthune Pro API key (wk_…). Required for models outside the free sample; the free models run without one."
    }
  }
}

try_household_projection

Run the deterministic multi-year household projection on a document you pass in — income, RMDs, Roth conversions, federal and covered-state tax, expenses, amortization, the tax-grossed-up deficit draw, and net worth per year — optionally with a seeded Monte Carlo. NOTHING IS STORED: no household is created, no id issued, no record kept. Takes any key, a free sandbox key included (worthune.com/sandbox). The response carries every simplification that fired in projection.assumptionsApplied and an evidence record whose hash reproduces on an identical document, so you can show your work. Use list_example_households for a starting shape. For a household that persists — with an id, bulk import, webhooks and drift detection — see create_household.

read-only

Argument	Type	Description
policy	object
api_key	string	Worthune API key (wk_…); a free sandbox key works
horizon*	object
household*	object	A household document: { schemaVersion, filingStatus, state?, members[], accounts[], liabilities[], incomes[], expenses[] }. It has no name field and no account numbers by design. Any expense `label` is stripped before anything is computed.
monteCarlo	object	Simulations are clamped to 500 on this surface, and the clamp is reported back.
assumptions

verify_claim

Verify claims about a model's outputs against the engine before presenting them to a user. Pass the model inputs plus one or more claims ({path, op, value}); each claim comes back verified, violated, or out-of-scope, with the engine's computed value as proof and a decision-record hash tying the verdict to this spec version and these inputs. Out-of-scope means the model does not compute the claimed quantity — this tool never guesses. Use it to check a number you are about to state; use run_model when you want the full output envelope.

read-only

Argument	Type	Description
model*	string	Model name from list_models
claims*	array	Claims to check (max 50)
inputs*	object	Model inputs per the contract's domains
api_key	string	Worthune Pro API key (wk_…). Required for models outside the free sample; the free models verify without one.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "model",
    "inputs",
    "claims"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "Model name from list_models"
    },
    "claims": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "path",
          "value"
        ],
        "properties": {
          "op": {
            "enum": [
              "==",
              "<",
              "<=",
              ">",
              ">="
            ],
            "type": "string",
            "description": "Comparison (default ==)"
          },
          "path": {
            "type": "string",
            "description": "Output path, e.g. \"monthsToBreakEven\" or \"schedule[3].balance\""
          },
          "value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              },
              {
                "type": "boolean"
              }
            ],
            "description": "Claimed value; non-finite numbers as \"Infinity\"/\"NaN\" strings"
          }
        }
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Claims to check (max 50)"
    },
    "inputs": {
      "type": "object",
      "description": "Model inputs per the contract's domains",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "api_key": {
      "type": "string",
      "description": "Worthune Pro API key (wk_…). Required for models outside the free sample; the free models verify without one."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id",
    "strategy",
    "horizon"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "exclusiveMinimum": 0
    },
    "params": {
      "type": "object",
      "description": "Strategy-specific parameters (see the tool description)",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…)"
    },
    "horizon": {
      "type": "object",
      "required": [
        "startYear",
        "years"
      ],
      "properties": {
        "years": {
          "type": "integer",
          "maximum": 80,
          "minimum": 1
        },
        "startYear": {
          "type": "integer",
          "maximum": 2150,
          "minimum": 1900
        }
      },
      "additionalProperties": false
    },
    "profile": {
      "type": "object",
      "required": [
        "id",
        "version"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      }
    },
    "strategy": {
      "enum": [
        "withdrawal-sequencing",
        "roth-ladder",
        "ss-claiming",
        "asset-location",
        "tax-loss-harvesting",
        "annual-gifting",
        "pension-election",
        "bracket-fill",
        "charitable-giving"
      ],
      "type": "string"
    },
    "assumptions": {
      "type": "object",
      "required": [
        "annualReturn",
        "inflationRate",
        "defaultIncomeGrowth"
      ],
      "properties": {
        "annualReturn": {
          "type": "number"
        },
        "inflationRate": {
          "type": "number"
        },
        "returnsByWrapper": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        },
        "socialSecurityCola": {
          "type": "number"
        },
        "defaultIncomeGrowth": {
          "type": "number"
        }
      },
      "additionalProperties": false
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "household",
    "horizon",
    "assumptions"
  ],
  "properties": {
    "policy": {
      "type": "object",
      "properties": {
        "rothConversions": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "year",
              "amountUsd"
            ],
            "properties": {
              "year": {
                "type": "integer",
                "maximum": 9007199254740991,
                "minimum": -9007199254740991
              },
              "amountUsd": {
                "type": "number"
              }
            }
          }
        },
        "withdrawalOrder": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "api_key": {
      "type": "string",
      "description": "Worthune API key (wk_…); a free sandbox key works"
    },
    "horizon": {
      "type": "object",
      "required": [
        "startYear",
        "years"
      ],
      "properties": {
        "years": {
          "type": "integer",
          "maximum": 80,
          "minimum": 1
        },
        "startYear": {
          "type": "integer",
          "maximum": 2150,
          "minimum": 1900
        }
      },
      "additionalProperties": false
    },
    "household": {
      "type": "object",
      "description": "A household document: { schemaVersion, filingStatus, state?, members[], accounts[], liabilities[], incomes[], expenses[] }. It has no name field and no account numbers by design. Any expense `label` is stripped before anything is computed.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "monteCarlo": {
      "type": "object",
      "properties": {
        "seed": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        },
        "longevity": {
          "type": "boolean"
        },
        "simulations": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991
        }
      },
      "description": "Simulations are clamped to 500 on this surface, and the clamp is reported back.",
      "additionalProperties": false
    },
    "assumptions": {
      "type": "object",
      "required": [
        "annualReturn",
        "inflationRate",
        "defaultIncomeGrowth"
      ],
      "properties": {
        "annualReturn": {
          "type": "number"
        },
        "inflationRate": {
          "type": "number"
        },
        "returnsByWrapper": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        },
        "socialSecurityCola": {
          "type": "number"
        },
        "defaultIncomeGrowth": {
          "type": "number"
        }
      },
      "description": "Required here: this surface has no org profile to fall back on.",
      "additionalProperties": false
    }
  }
}