santismm-knowledge

Official

by santismm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Calculate the ROI and TCO of a robot fleet

calculate_physical_ai_roi

Read-onlyIdempotent

Calculate 36-month ROI for a robot fleet: compare manual vs robotic TCO, annual savings, upfront investment, payback month and sensitivity to cost, capex and uptime.

Instructions

Run the Physical AI calculator's own 36-month model: manual vs robotic TCO, annual savings, upfront investment, payback month, ROI, coverage, supervision and incidents, plus payback sensitivity to hourly cost, capex, coverage, integration, maintenance and uptime. Every input is optional; use_case applies a published preset first. The response lists the assumptions with their evidence level and the fields_to_validate that are still editorial defaults — tell the user to replace them. Orientative, undiscounted, single currency; not a quote. Use this for the cost, savings or payback of a robot fleet; for an AI-agent business case use calculate_agent_economics.

Input Schema

Name	Required	Description
`risk`	No	Hazard level: scales incident cost and adds a labour risk premium.
`fleet`	No	Per robot class; any field omitted keeps its default.
`locale`	No	Language of the returned body. Default: en.
`use_case`	No	Apply this automation-matrix preset before the other inputs.
`uptime_pct`	No	Robot availability, 0–100 %.
`hourly_cost`	No	Fully loaded hourly labour cost, in the chosen currency.
`days_per_year`	No	Operating days per year.
`error_rate_pct`	No	% of tasks (≈ one per labour hour) that end in an incident.
`horizon_months`	No	Default 36.
`shifts_per_day`	No	Shifts per day.
`hours_per_shift`	No	shifts_per_day × hours_per_shift may not exceed 24.
`integration_cost`	No	One-off integration cost, in the chosen currency.
`cost_per_incident`	No	Average cost of one incident, in the chosen currency.
`operators_per_shift`	No	People per shift doing the work today.
`robots_per_supervisor`	No	Robots one supervisor can oversee at once.

Output Schema

Name	Required	Description	Default
`locale`	No
`api_version`	Yes
`model_version`	No
`dataset_version`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.6.0Nov 6, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the readOnly/idempotent annotations, it discloses that every input is optional, that use_case applies a published preset before other inputs, and that the response carries assumption evidence levels plus fields_to_validate that are editorial defaults the user should replace. It also states scope limits (orientative, undiscounted, single currency, not a quote). The only gap is no mention of rate limits or response size, minor for a stateless calculator.

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

Conciseness4/5

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

Purpose and model scope are front-loaded in the opening clause, and every subsequent sentence adds routing, caveats, or output trust guidance. The middle sentence is a long comma-run list of outputs and sensitivity drivers that could be tightened, but nothing is wasted or repeated from the schema.

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 15-parameter nested tool with a full output schema, the description covers what an agent needs: what is computed, that inputs are optional with defaults and presets, how to treat unvalidated defaults, and when to pick the sibling instead. Return-value detail is correctly left to the output schema.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already carries the baseline burden; the description adds the ordering semantics of use_case versus explicit inputs and the overall optionality/defaults behavior that the schema only states per field. It also names the drivers the payback sensitivity responds to, which helps the agent reason about which inputs matter most.

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?

States a specific verb and resource ('Run the Physical AI calculator's own 36-month model') and enumerates the concrete outputs (manual vs robotic TCO, payback month, ROI, sensitivity). It explicitly contrasts itself with the nearest sibling, calculate_agent_economics, so an agent can route without opening either schema.

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?

Gives an explicit selection rule: use this for the cost, savings or payback of a robot fleet, and use calculate_agent_economics for an AI-agent business case. That is a direct when-to-use/when-not-to-use pair naming the alternative, not implied guidance.

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