Ptally

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.

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.

Dry-run a quote against a stored project. 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. 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.