DEV Community: Zachariah M

A calculator tool should return its assumptions, not just a payback number

Zachariah M — Tue, 27 Oct 2026 18:02:00 +0000

Disclosure: Prepared with AI assistance from the current implementation and live checks using fictional inputs.

We exposed Aplos's automation-budget arithmetic as a small MCP tool. The useful design decision was separating cash expenditure from the assigned value of people's time.

Those values can be added in a model, but they should not be presented as the same thing. A workflow might free staff capacity while leaving payroll unchanged.

Make the assumptions explicit

The calculate_automation_budget tool accepts seven numbers:

{
  "setup": 5000,
  "rollout": 10,
  "software": 200,
  "support": 100,
  "review": 5,
  "rate": 40,
  "hours": 40
}

setup is the one-time cash cost. rollout is internal rollout time in hours. software and support are monthly cash costs. review is monthly review and maintenance time. rate assigns a value to an hour, and hours is gross monthly time expected to be freed.

Every input is required. Use zero for an inapplicable cost, and use one currency consistently. The tool validates finite numbers from zero to one million and rejects additional fields. That keeps a caller from silently supplying an unsupported tax rate or another assumption the calculation ignores.

Return the components

For the example above, the calculation is:

Monthly cash cost = 200 + 100 = 300
Monthly economic cost = 300 + (5 × 40) = 500
Upfront economic cost = 5000 + (10 × 40) = 5400
Monthly net capacity value = (40 × 40) - 500 = 1100
Simple economic payback = 5400 / 1100 = 4.91 months
First-year cash outlay = 5000 + (12 × 300) = 8600

The response includes these components and echoes the assumptions in structured content. The caller can show where the headline number came from and which inputs the user should challenge.

Test the uncertain assumption

Holding the costs constant and changing gross time freed from 40 to 15 hours reduces monthly net capacity value to 100. Simple payback becomes 54 months. At 10 hours, modeled monthly net value is negative, so the tool returns null for payback.

That null matters. Returning a negative payback period would make a losing scenario look like a valid schedule. A client should explain that the current assumptions produce no positive monthly net value.

The calculation does not establish that a project will free the forecast hours. That evidence has to come from observing the workflow. It also excludes taxes, financing, discounting and currency conversion.

Keep the tool's claims narrow

The server performs arithmetic. It does not read accounting records, remove expenses, purchase software or promise savings. Its tool annotations describe it as read-only, non-destructive and idempotent, with no open-world actions.

Invalid values produce an explicit tool error. Valid responses include an interpretation explaining that time-valued capacity becomes cash savings only if a real expense is removed. This makes the limitation available to the client alongside the numeric result.

We checked initialization, tool discovery and eight fictional valid/invalid cases against the live endpoint. Those checks verify the examples and input behavior; they are not evidence of economic returns or ChatGPT directory approval.

Try the browser calculator, or see the MCP connection details.

An extraction result should not also be permission to export

Zachariah M — Wed, 14 Oct 2026 21:48:27 +0000

In Aplos Document Desk, the model produces a draft. A separate state transition decides whether that draft can become a CSV.

That boundary matters because a plausible value can still be wrong. A date may have two interpretations. A total may appear several times. A credit note can become a positive number if a parser loses the sign.

Here is how the shipped implementation separates extraction, review and export. This is a description of our implementation, not a claim that the approach eliminates document errors.

Store a candidate and its evidence separately

The extractor returns fields with a value and a source quote. Application code normalizes the candidate and checks whether the quoted text occurs in the extracted source. It retains an anchor for the review interface.

A matching quote establishes that text exists. It does not establish that the text is the correct field, or that OCR read the original image accurately. The original page preview remains available next to the draft.

Money fields need more than substring matching. If the document says (156.60), finding 156.60 inside it does not support a positive amount. Our wrapper inspects the surrounding printed sign and rejects a positive candidate drawn from a negative source amount.

Ambiguous dates and unsupported currencies remain unresolved. Filling every cell is not a useful goal if doing so requires a guess.

Make review a server-side state transition

Documents begin as queued or processing, then become drafts. A reviewer can save changes, exclude a document or explicitly mark it reviewed. Required-field errors prevent review. Warnings, including possible duplicates and inconsistent totals, require acknowledgement and a review note.

Every update carries a version. The server rejects stale changes when another update has already changed that document. Saving an edit resets its review state.

Duplicate decisions also depend on the batch. If a supplier or reference changes and creates a possible duplicate with a previously reviewed document, that earlier review is invalidated. A green check must describe the current data, not an old version of it.

The simplified transition looks like this:

uploaded -> queued -> processing -> draft
draft -> reviewed, after required checks and explicit confirmation
draft -> excluded
reviewed -> draft, after a change that needs renewed review

This is explanatory pseudocode. The production implementation also handles interruptions, expiry and bounded retry.

Seal the artifact before checkout

Preparing an export happens inside a database transaction. Each included document must be reviewed; excluded documents are omitted. The server constructs the CSV once, saves its bytes and hash, and links the batch to that export job.

A repeated preparation request returns the existing job. Once sealed, the batch cannot silently change the file being purchased.

Payment fulfillment uses the existing server-side verification path. A successful browser redirect alone does not grant download access. The verified payment must match the intended account, mode, product, price, quantity, amount, currency and export job.

This separates three facts that are easy to blur together: a model returned fields, a person reviewed those fields, and a payment authorizes access to a particular artifact.

Test the transitions as well as the extractor

The useful cases are not limited to a clean invoice. We check ambiguous dates, negative amounts, duplicate files, supplier/reference collisions, stale updates, edits after review, export before review, download before payment and source access from another session.

Our development evaluation used owned synthetic documents. That helps expose implementation defects, but it does not establish customer-document accuracy, review speed or performance against another product. Every included document still requires review.

The public product supports small English invoice, receipt and credit-note batches and exports document totals. It does not extract line items or post accounting entries.

You can inspect the sample workflow at Aplos Document Desk. Preview is free; a reviewed CSV batch of up to twenty documents costs $9.

Disclosure: I build Aplos. This write-up was prepared with AI assistance and checked against the shipped extraction, review and export code.