Ptally

Amend a SAVED quote (a quote_reference from get_quotes): its price (`result`), and optionally `valid` or `sold`, with a required `reason`. Logged in the quote's audit trail under the signed-in user, with the time, the old and new values, source "mcp" and the reason. The engine's own result, valid and output are never changed — the amended values sit beside them, and setting price or validity back to the engine's value clears that amendment (still logged). BEFORE CALLING 1. Call get_quote (or get_quotes) for the quote's current price, validity and sold flag. 2. Tell the user exactly what will change (old → new) and the reason that will be logged, and get their go-ahead. RULES - At least one of result, valid, sold, and each must differ from what the quote is now (else an error says nothing changed). - result is a number; valid and sold are booleans; reason is a non-empty sentence. - A sold quote is locked. The only change it accepts is `sold: false` on its own (marking it unsold, with a reason); after that it can be amended and marked sold again — three calls, each logged. Check get_quote first, and tell the user when a change means unselling the quote. A price change can go in the same call that marks it sold. - Refused in read-only mode. RESULT { quote_reference, engine: { result, valid }, now: { result, valid, sold }, amended, logged: { amendment_reference, by, at, source, result: { from, to }, valid, sold, reason }, quote_url, next_steps }.

Fetch Ptally documentation by topic. Call BEFORE building or editing a config to load the rules and reference material you need. Topics: "rules" = agent rules, constraints, expression syntax, quality gates, and debugging guidance (start here); "readme" = full engine reference with step types, query language, input/output blocks, and code examples.

Diagnostic snapshot of the deployed MCP server plus a live probe of its store (sqlite or Postgres). Returns server name and version, protocol version, root, boot time, advertised tool names and count, a hash of the tool surface, and `store` — `{ ok, latency_ms, counts: { projects, quotes } }` from counting rows in the projects table (one row per version) and the quotes table, or `{ ok: false, latency_ms, error }`.

Fetch a project by `project_reference` from the self-host store. Optional `version_reference` pins to a specific version of that project (a version from another project is a tool error); otherwise the latest live (published or approved) version is used, or the latest non-archived version of any status if none is live. Returns `{ project_reference, version_reference, version, name, description, status, summary, created_at, updated_at, project_url, version_url, latest_draft, clipped_collections, next_steps, model }`. The model is a summary for reading, never a file to hand back. Every `collection` step is stamped with `__context` (`total_rows`, `shown_rows`, `columns`, `shape`, `truncated`, `patchable`; an empty table gets `total_rows: 0`, `columns: []`, `patchable: true`): tables of up to 100 rows are shown whole and can be changed with patch_version; bigger ones are clipped, listed in `clipped_collections`, and can only change by the user downloading the model from `version_url`, you amending it, and the user uploading it. `latest_draft` is the newest draft version (null if none) — patches go there, so call get_project again with its version_reference before patching. Follow `next_steps` and tell the user which route applies before making changes. All other model content — input.format, steps, expressions, output — is returned verbatim so an LLM caller can understand what the project does and how to build a valid input payload. Precursor to run_quote and patch_version.

List every project stored on this self-host instance. Returns `{ count, projects: [{ project_reference, name, description }] }`. Descriptions are truncated to 100 characters so the response stays compact — call get_project for the full record. Archived projects are excluded.

Review one quote in a standard shape, from a stored `quote_reference` (get_quotes) or a pasted `quote` — the dashboard's Copy JSON, a POST /quotes or run_quote response, or a bare engine output with `debug` (`quote_gz`: base64 gzip of the same JSON, for big pastes). Pass exactly one. Returns `{ source, quote_reference, project_reference, project_name, version_reference, version, created_at, outcome: { decision (quoted | declined | referred | error), result, valid, status, error, exec_time_ms, engine_time_ms, steps, slowest_steps }, input, output, rules: { exclusions, refers, excesses, endorsements: { fired_count, checked_count, fired: [{ step, name, exp, values, result }] } }, result_build: { formula, values, result }, valid_rule: { exp, values, result }, build: [{ order, id, name, type, description, ms, logic: [{ name, exp | formula, values, result }], lookups, table_rows, output, errors }], errors, has_trace, truncated, amendment, quote_url, version_url, replay, how_to_explain, next_steps }`. `outcome` is always what the engine priced. `amendment` (stored quotes only; null when never touched) is `{ result, valid, sold, amended_at, log: [{ when, who, via (dashboard | api | mcp), result: { from, to }, valid, sold, note }] }`: the price, validity or sold flag someone set afterwards (dashboard, API or amend_quote), and the log of who changed what. Step names, types, descriptions and collection lookups come from the version's model when it is on this instance. A quote without a step trace is re-priced against its version (`replay: true` forces it); `replay` reports the replayed vs stored result and whether they match. Nothing is saved. Responses are kept under ~80 KB: large quotes come back clipped or as an overview (`truncated` says which) — pass `steps: [<id>, …]` for those steps in full. If even the overview is too big the result is `{ too_large: true, outcome, rules counts, next_steps }`: review a few steps at a time, or ask the user to paste the part they want explained. Explain the result back following `how_to_explain`.

List quotes stored on this self-host instance, newest first (`direction: "asc"` for oldest first). Filter by `project_reference` (from get_projects), `version_reference`, `since` (ISO date) or `search` (text match on indicators). Paged with `limit` (default 25, max 100) and `offset`; `has_more` says whether another page exists. Returns `{ count, limit, offset, has_more, quotes: [{ quote_reference, project_reference, project_name, version_reference, version, created_at, status, valid, result, indicator, client_ref, exec_time_ms, error, amended_result, amended_valid, sold, quote_url }], next_steps }` — `result` and `valid` are what the engine priced; `amended_result` / `amended_valid` (null when not amended) are what someone changed them to in the dashboard, and `sold` (null when never set) whether it sold. No input or output payloads; call get_quote for one quote's full review. Dry runs (run_quote without save, run_version_tests) are never stored, so they never appear here; run_quote with save: true does.

Fetch the full JSON schema for Ptally project config files. Use to check exact field requirements, allowed step types, and property constraints.

Fetch a worked-example Ptally project for a common line of business. Each example is a small, fully valid project with realistic collection tables, calculations, exclusions and refers, plus an embedded tests[] suite for reference. Use as a template — copy and adapt rather than authoring from scratch. Pass no arguments (or `list: true`) to get the catalog.

Change a DRAFT version's stored model with an RFC 6902 JSON Patch, merged on the server. Use it for targeted edits; any change to a clipped collection (__context.patchable: false) goes through download and upload instead (see next_steps in get_project). BEFORE CALLING 1. The version must be a draft: use get_project's latest_draft. If it is null, ask the user to click New Version on the project page (it copies the live model), then call get_project again. 2. Call get_project with the draft's version_reference and build every path from that response. Pass its updated_at as base_updated_at. 3. Tell the user what you will change (old → new) and get their go-ahead. PATHS (JSON Pointer) - Name steps, tests and other id'd array elements by id (else key) instead of index: /steps/<step id>/... and /tests/<test id>/... Ids survive other steps being inserted or removed in the same patch. - Model layout: /meta/..., /input/format/<input key>/... (format is an object keyed by input key), /steps/<id>/..., /output/format/<key>/..., /tests/<id>/... - Collection rows by index. Compressed collection ([[col1, col2, ...], [v1, v2, ...], ...]): index 0 is the header row, so the first data row is /collection/1, and a cell is /collection/<row>/<column index>. Uncompressed collection (array of row objects): the first row is /collection/0, and a cell is /collection/<row>/<column name>. Check __context.shape and __context.columns. - Append with "-" (/steps/-, /steps/<id>/collection/-). Insert at a numeric index; step order is execution order, so a new step goes after the steps whose outputs it reads. - Escape "~" as ~0 and "/" as ~1 inside a segment. EXAMPLES - Change a rate cell: {"op":"replace","path":"/steps/region_rates/collection/1/1","value":4.5} - Guard then change: [{"op":"test","path":"/steps/base_premium/formula","value":"<current formula>"},{"op":"replace","path":"/steps/base_premium/formula","value":"<new formula>"}] - Add a table row: {"op":"add","path":"/steps/type_factors/collection/-","value":["gravel",1.1]} - Change an input default: {"op":"replace","path":"/input/format/bike_value/def","value":2000} - Insert a step as the 5th: {"op":"add","path":"/steps/4","value":{ ...full step object... }} - Update a test's expected price: {"op":"replace","path":"/tests/t01/output/result","value":46.1} - Add a test: {"op":"add","path":"/tests/-","value":{"id":"young_rider","name":"Young rider","key":"young_rider","input":{ ...every input key... },"output":{"result":52.5,"valid":true}}}. Expectations go in output { result, valid }, even if older tests on the model keep them under result. RULES - Smallest change: replace a field, not a whole step; never the whole model (path "" is refused). - New or replaced steps follow the config constraints in the server instructions (retain: true on transforms, unique id = key, {{}} references, ...). - Don't send __context (it's stripped anyway). A clipped collection must stay exactly as stored — no edits, no removal, no replacement with the sample you saw. A patched collection may hold at most 100 rows. - All operations apply or none do. At most 200 per call. RESULT { saved, updated_at, validation, tests: { total, passed, failed, unchecked, failures: [{ test, problems }] }, version_url, next_steps }. saved: false = schema validation failed, nothing stored — fix from validation.errors and retry. A conflict error = the draft changed since you read it — call get_project again and rebuild. Tests are priced after saving and don't block it: report failures and ask whether their expected outputs should change. For every test's actual vs expected values, call run_version_tests. For another patch, use the returned updated_at. Never approves or publishes — the user does that in the UI.

Price a quote against a stored project: a dry run by default, saved only with `save: true`. Takes `project_reference`, an optional `version_reference` (defaults to the latest live version; there is no fallback to drafts, so pass `version_reference` to price one — it must belong to the project and not be archived, else a tool error), and an `input` payload that matches the project's input schema. Runs the pricing engine and returns the quote envelope — `output`, `result`, `valid`, `status`, `error`, the engine's `errors` log, `exec_time_ms`, `dry_run: true` and a null `quote_reference` — WITHOUT persisting a quotes row. With `save: true` the quote is stored like a POST /quotes, under the signed-in user (an engine error is stored as an error quote), and the envelope carries `dry_run: false`, its `quote_reference`, `created_at` and `quote_url`; it then shows in get_quotes and the dashboard and can be amended with amend_quote. Only save when the user asks for the quote to be kept, not to try inputs. Saving is refused in read-only mode. Call get_project first to inspect `input.format` and build a valid input.

Price every test in a version's tests[] against that version's stored model and compare each with its expected output. Takes `version_reference` (any status but archived — a draft after patch_version, or a live version for a baseline). Runs against the stored model, so a patch saved a moment ago is included. A test passes when its result is within 0.005 of the expected result and its valid flag equals the expected valid. Expectations are read from output { result, valid }, or, when output has neither (tests imported from the hosted service), from result { result, valid }; `expected_from` says which. A test with neither is priced but unchecked (passed: null). Returns `{ project_reference, version_reference, version, status, updated_at, total, passed, failed, unchecked, results: [{ id, name, passed, expected: { result, valid }, expected_from, actual: { result, valid }, problems, errors }], version_url, next_steps }` — `problems` says why a test failed, `errors` is up to 5 of the engine's step errors for that run. Nothing is persisted. Use after patch_version, after adding or changing tests, or before a change to record the baseline. To change a test's expected output, patch_version on /tests/<test id>/output/result (drafts only) — output takes precedence over result.

Server-side schema validation of a project config. Returns { valid: true/false, errors: [...] } with the JSON path, keyword, and message for each issue. Prefer local validation against get_schema during authoring; use this as a ground-truth check, including on an amended model before handing it back to the user as a file. Pass exactly one of inline `project` or a base64-gzipped `project_gz` (if the inline form is too large for your client); passing neither or both returns an error result.