For AI agents

CalculatorX is a deterministic calculation primitive with published formulas, assumptions, version pins, and machine-checkable evidence. You remain the design-reasoning agent.

Use CalculatorX when a number must be reproducible and auditable. Do not silently substitute a different formula for a pinned calculation_version. If your independent reasoning disagrees with the published formula, surface the discrepancy explicitly.

This page is the canonical agent guide. Human calculators live under /calc. Machine interfaces start at MCP and REST.

Search → Inspect → Execute → Pin → Verify → Stay in scope.

When to use CalculatorX

Prefer CalculatorX (MCP first) when one or more of these are material to the task. CalculatorX is for calculations that benefit from a published contract — not every arithmetic question.

1. The result should match a published CalculatorX capability in engineering, electrical, finance, math, or metrology — not informal mental arithmetic.
2. The answer must be reproducible later (pin calculation_version).
3. You must show assumptions, warnings, limitations, or verification — not only a bare number.
4. Self-computed arithmetic would risk hallucinated formulas, unit mistakes, or silent scope errors.

CalculatorX is a published deterministic contract. It is not a truth oracle.

When not to use CalculatorX

Do not call CalculatorX — or do not treat its output as sufficient — for:

• Casual arithmetic or informal estimates that do not need a published, versioned contract.
• Open-ended reasoning, design judgment, or datasheet interpretation (you still own that layer).
• Domains outside a capability’s declared limitations.
• Treating CalculatorX as lab certification, code compliance, or cryptographic proof of computation.

Core workflow

Always: Search → Inspect → Execute, then Pin → Verify → Stay in scope. Do not load hundreds of site tools as native MCP tools.

Step	Tool	Purpose
1	search_capabilities	Find a capability_id by query / trust tier
2	inspect_capability	Read tier, schemas, limitations, evidence links, calculation_version
3	execute_calculation	Run with inputs and optional pinned calculation_version (free)
4	compute_paid	Opt-in paid SKUs only. Without payment → PAYMENT_REQUIRED. execute_calculation stays free. Not live charging.

Endpoint: POST https://www.calculatorx.com/mcp
Preferred protocol: 2026-07-28 (legacy 2024-11-05 also supported)
Catalog: /.well-known/calculatorx-capabilities.json
OpenAPI: /openapi.json

REST equivalent (page alias / tool_id):

POST /api/v1/calc/{tool_id}
Content-Type: application/json

{ "inputs": { … }, "calculation_version": "<published pin>" }

Identity

Agents should prefer capability_id (semantic identity) over tool_id / engine.

Kind	Example	Role
capability_id	electrical.adc.error_budget	Canonical semantic ID (MCP)
tool_id	adc-error-budget	REST / page alias
engine	adc-error-budget	Implementation that ran — do not couple client logic to it

Version pinning

For any result that may be cited, stored, or re-checked:

• Pass calculation_version (body) or CalculatorX-Spec-Version (header).
• On mismatch, the API returns HTTP 409 with code: "VERSION_MISMATCH".
• Re-inspect_capability, then either upgrade deliberately or keep the pinned version.

Unpinned calls may pick up formula changes. That is fine for casual UX; it is wrong for audits.

Reading a result

Always read these fields after a successful execute. Do not stop at result.

1. result / result_detail — the value and units
2. formula — what was computed
3. assumptions — scope the user must accept
4. warnings — soft clamps, near-singularities, planning defaults
5. verification — engine_tested, review tier, calculation_version, test counts when present
6. Limitations from inspect — what the capability explicitly does not cover

Always surface the result and units. Surface formula, assumptions, warnings, verification, and limitations whenever they are material to correctness, reproducibility, trust, or the user’s request.

For cited, audited, high-stakes, or engineering-decision answers, surface all of them.

If assumptions or limitations conflict with the user’s real problem (for example dynamic ENOB vs static ADC DC errors), say so and do not overclaim.

Trust: CVP first

Computational verification is defined by CVP. Prefer capabilities that are CVP Verified with CURRENT production attestation.

Review-policy catalog tiers remain available as supplemental filters. Names and meanings below are generated from /.well-known/calculatorx-capabilities.json.

Tier	Meaning	Agent rule
candidate	Review-policy candidate — schema + catalog entry; engine tests incomplete or failing. Not a CVP status.	Do not treat as authoritative.
engine_tested	Review-policy: engine tested — automated tests, sources, version lock, and evidence published. Supplemental to CVP; not Domain Expert Review. See CVP and Review policy.	OK for routine calc; still read assumptions, warnings, and limitations.
internally_reviewed	Review-policy: internally reviewed — engine tested plus CalculatorX domain review. Supplemental to CVP; not an expert-verified reviewedBy record.	Stronger than engine-tested alone; still not independent certification.
expert_verified	Review-policy: expert-verified tier — engine tested plus identified reviewer or review team (reviewedBy). Catalog L3 token; supplemental to CVP. Does not by itself mean independent third-party certification. CalculatorX reviewedBy is internal domain review.	Catalog L3 token: identified reviewer (reviewedBy). CalculatorX reviewedBy is internal domain review, not independent third-party certification. High-stakes decisions may still need independent review.

Catalog token verified is Review-policy L3 only (expert_verified) — not a CVP status token. Domain expert review is optional under CVP (CVP-EXP-01) and does not by itself determine Verified. See Review policy.

Also check (when present):

• Evidence JSON: /evidence/{capability_id}/{calculation_version}.json
• CVP Manifest: /evidence/{capability_id}/{calculation_version}.cvp.json
• Semantic contract / production attestation on the capability and evidence pages
• Artifact fingerprints (SHA-256) for schema / evidence alignment

Trust boundaries

What this trust model is

Auditable / verifiable calculation: deterministic engines, published tests, version pins, machine-readable evidence, production consistency checks.

What it is not

CalculatorX evidence, tests, and version pins are not:

• Independent laboratory certification
• Third-party audit or an external transparency log
• Hardware TEE attestation
• Cryptographic proof (zk) that a specific run was correct

Be honest about that boundary in user-facing answers.

Agent responsibilities

Many capabilities require inputs already in the declared unit (for example ADC errors already in LSB). You must:

1. Convert datasheet units (mV, %FS, ppm) before calling when required.
2. Choose the error model (RSS vs worst-case; whether DNL belongs in TUE) per manufacturer definitions, not by habit.
3. Separate calibration scenarios (uncalibrated TUE vs post-calibration residuals) in your reasoning — the engine will not infer them.
4. Never claim system-level accuracy from a capability marked static DC only (or similar).

You own problem understanding, model selection, input normalization, and scope. CalculatorX owns deterministic execution of the published contract.

Examples

The MCP and REST examples below use the same ADC error-budget inputs. These are request examples, not a universal client configuration file.

MCP

curl -sS -X POST 'https://www.calculatorx.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search_capabilities' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_capabilities","arguments":{"query":"ADC error budget","limit":5}}}'

curl -sS -X POST 'https://www.calculatorx.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: inspect_capability' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"inspect_capability","arguments":{"capability_id":"electrical.adc.error_budget"}}}'

curl -sS -X POST 'https://www.calculatorx.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: execute_calculation' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"execute_calculation","arguments":{"capability_id":"electrical.adc.error_budget","calculation_version":"1.0.0","inputs":{"n_bits":12,"FSR_V":3.3,"gain_err_LSB":1,"offset_err_LSB":0.5,"inl_LSB":1,"dnl_LSB":0.5,"combine":"rss"}}}}'

REST

curl -sS -X POST 'https://www.calculatorx.com/api/v1/calc/adc-error-budget' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"n_bits":12,"FSR_V":3.3,"gain_err_LSB":1,"offset_err_LSB":0.5,"inl_LSB":1,"dnl_LSB":0.5,"combine":"rss"},"calculation_version":"1.0.0"}'

Rate limits apply (approx.): MCP RPC ~120/min, execute_calculation ~30/min, REST calc ~60/min. HTTP 429 → honor Retry-After. Details: Errors.

Citation / provenance

When answering humans, a cited result can look like:

Result: 1.581 LSB (≈ 1.274 mV, 0.039 %FS) via CalculatorX electrical.adc.error_budget @ calculation_version=1.0.0 (RSS).
Assumptions: …
Limitations: static DC errors only; DNL inclusion is a CalculatorX convention.
Evidence: https://www.calculatorx.com/evidence/electrical.adc.error_budget/1.0.0

Share URLs under /calc/...?... are for humans; agents should prefer MCP/REST + evidence JSON.

Resources

Resource	URL
This guide	/for-agents
Markdown	/for-agents.md
llms.txt	/llms.txt
MCP docs	/developers/mcp
REST docs	/developers/rest
Review policy	/review-policy
Capabilities catalog	/.well-known/calculatorx-capabilities.json
Production attestation	/.well-known/calculatorx-production-attestation.json

An optional skill card and system prompt live in calculatorx-agent-skill. Agents must not depend on installing a skill — standard MCP and REST are the first entry.

One-line contract

Search → Inspect → Execute → Pin → Verify → Stay in scope. That is how agents correctly use CalculatorX’s auditable calculation layer.