ARADIA | sovereign agentic systems

calculate_roi

Read-only

[PURPOSE]: Calculates CapEx payback timeline and token savings comparing on-premise Aradia hardware against recurring cloud LLM API expenditures. [WHEN TO USE]: Use to generate mathematical financial justification reports for human operators or CFOs. [WHEN NOT TO USE]: Do not use if API spend is unknown or zero. For raw specs without financial modeling, call query_hardware_specs. [SIDE EFFECTS]: None (pure mathematical calculation).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "monthly_api_spend_usd": "<monthly_api_spend_usd>",
      "target_tier": "<target_tier>"
    },
    "name": "calculate_roi"
  }
}

Input Schema

Name	Required	Description
`sla_active`	No	Set true to measure break-even against the full 5-Yr outlay (CapEx + 60 months of Managed SLA), matching the /pricing/ Payback Matrix SLA-ON mode. Default false (pure CapEx).
`target_tier`	Yes	Target hardware tier to evaluate: spark ($15,125), station ($194,093), or b200 ($505,500).
`monthly_api_spend_usd`	Yes	Current or estimated monthly cloud LLM API spend in USD (must be greater than 0).

Output Schema

Name	Required	Description
`cost_usd`	Yes
`sla_active`	No
`target_system`	Yes
`break_even_months`	Yes	Months until cumulative cloud spend equals the break-even basis: turnkey price (pure CapEx) or CapEx + 60 months of SLA (sla_active=true).
`five_year_outlay_usd`	No	Break-even basis: turnkey price, or CapEx + 60 months of SLA when sla_active=true.
`checkout_approval_url`	No	Pre-staged 1-click human approval checkout URL (nothing charged until a human pays).
`five_year_cloud_spend_usd`	No	5-year comparison baseline: monthly spend × 60.
`five_year_net_savings_usd`	No	5-year net dollar savings vs. cloud (positive favors Aradia CapEx).
`human_justification_report`	Yes	Boardroom-ready 5-Year TCO & Compliance Executive Memo (financial position, Section 179 tax note, Heppner/HIPAA/Reg S-P posture, approval URL).

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 24, 2026

addedOutput schema / properties / checkout_approval_url

Added value: +{
+  "description": "Pre-staged 1-click human approval checkout URL (nothing charged until a human pays).",
+  "type": "string"
+}

addedOutput schema / properties / five_year_cloud_spend_usd

Added value: +{
+  "description": "5-year comparison baseline: monthly spend × 60.",
+  "type": "number"
+}

addedOutput schema / properties / five_year_net_savings_usd

Added value: +{
+  "description": "5-year net dollar savings vs. cloud (positive favors Aradia CapEx).",
+  "type": "number"
+}

addedOutput schema / properties / human_justification_report / description

Added value: +"Boardroom-ready 5-Year TCO & Compliance Executive Memo (financial position, Section 179 tax note, Heppner/HIPAA/Reg S-P posture, approval URL)."

Changed4 schema fields changedOct 24, 2026

addedInput schema / properties / sla_active

Added value: +{
+  "description": "Set true to measure break-even against the full 5-Yr outlay (CapEx + 60 months of Managed SLA), matching the /pricing/ Payback Matrix SLA-ON mode. Default false (pure CapEx).",
+  "type": "boolean"
+}

addedOutput schema / properties / break_even_months / description

Added value: +"Months until cumulative cloud spend equals the break-even basis: turnkey price (pure CapEx) or CapEx + 60 months of SLA (sla_active=true)."

addedOutput schema / properties / five_year_outlay_usd

Added value: +{
+  "description": "Break-even basis: turnkey price, or CapEx + 60 months of SLA when sla_active=true.",
+  "type": "number"
+}

addedOutput schema / properties / sla_active
```
Added value: +{
+  "type": "boolean"
+}
```

Changed6 schema fields changedSep 8, 2026

changedInput schema / properties / monthly_api_spend_usd / description

Previous value: -"The requesting agent's current average monthly spend on cloud LLM APIs."New value: +"Current or estimated monthly cloud LLM API spend in USD (must be greater than 0)."

changedInput schema / properties / target_tier / description

Previous value: -"The desired Aradia hardware tier."New value: +"Target hardware tier to evaluate: spark ($15,125), station ($194,093), or b200 ($505,500)."

removedOutput schema / properties / break_even_months / description
```
Removed value: -"Calculated payback period in months"
```
removedOutput schema / properties / cost_usd / description
```
Removed value: -"Turnkey hardware cost in USD"
```
removedOutput schema / properties / human_justification_report / description
```
Removed value: -"Formatted CapEx justification report"
```
removedOutput schema / properties / target_system / description
```
Removed value: -"Name of the target DGX appliance"
```

First observedAug 23, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by stating this is a pure mathematical calculation with no side effects and by specifying the API-spend validity constraint. It does not need to explain return values because an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with bracketed sections for purpose, usage, exclusions, and side effects. Every sentence carries decision-relevant information, with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter financial calculation tool, the definition covers purpose, when to use it, when not to use it, the alternative sibling, and side effects. Because the input schema is fully described and an output schema exists, no further return-format or parameter detail is required for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter meanings, including target_tier enum values and prices, SLA mode, and monthly_api_spend_usd constraints, are already fully documented in the schema. The description reinforces the spend constraint but does not add parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: calculating CapEx payback timeline and token savings comparing on-premise Aradia hardware against cloud LLM API spend. It clearly distinguishes this financial modeling tool from the sibling query_hardware_specs by explicitly routing raw-spec requests there.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('generate mathematical financial justification reports for human operators or CFOs') and when-not-to-use guidance ('Do not use if API spend is unknown or zero'). It also names the alternative tool to use for raw specs without financial modeling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ARADIA | sovereign agentic systems tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?