boaviztapi-mcp

Compare estimates

compare_estimates

Read-onlyIdempotent

Compare 2 to 5 cloud instances, servers, components, or devices over a common period and rank them by impact criteria, totals, first-option differences, and uncertainty overlap.

Instructions

Compare 2 to 5 options (cloud instances, servers, components or devices) over one common period and rank them per criterion, with each total, the difference from the first option, and whether the uncertainty ranges overlap.

Use it whenever the question is which option is greener or how options differ; use the single estimate tools for one item. Each item has a label, a kind, and params holding the matching estimate tool's inputs (without duration_hours, criteria or detail). duration_hours is required so items with different lifetimes compare on equal terms. Every item is checked before any estimate runs, and an invalid item fails the call with its label named. Read-only: one BoaviztAPI request per item.

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": {
      "items": "<items>",
      "duration_hours": "<duration_hours>"
    },
    "name": "compare_estimates"
  }
}

Input Schema

Name	Required	Description
`items`	Yes	2 to 5 options.
`criteria`	No	Impact criteria codes; default gwp, adp, pe. See list_impact_criteria. 'all' is not accepted.
`duration_hours`	Yes	Common period in hours for every option (8760 = 1 year), so options with different lifetimes compare fairly.

Output Schema

Name	Required	Description	Default
`results`	Yes
`summary`	Yes
`comparison`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 13, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description still adds real behavior: every item is validated before any estimate runs, an invalid item fails the whole call with its label named, and it costs one BoaviztAPI request per item. It stops short of describing error types or partial-failure semantics, keeping it at 4 rather than 5.

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?

Front-loaded with what it does, then when to use it, then the input contract and failure behavior — a sensible order with little waste. The sentence enumerating label/kind/params largely restates the schema, a minor redundancy that keeps it from a 5.

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?

An output schema exists, so return values need no explanation; the description covers the remaining gaps an agent needs — when to pick this over the single-estimate tools, the required common period, the nested params contract, validation timing, and failure reporting. Nothing material for a correct invocation is missing.

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 coverage is 100%, so the baseline is 3; the description goes beyond it by explaining why duration_hours exists (equal-footing comparison across differing lifetimes) and by restating that params excludes duration_hours, criteria and detail — the most likely source of a malformed nested payload. The per-kind key lists live in the schema rather than the description, so it is not fully additive.

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 — compare 2 to 5 options and rank them per criterion — plus exactly what the output contains (totals, delta from the first option, overlapping uncertainty ranges). It also names the sibling class it is not ('use the single estimate tools for one item'), so an agent can separate it from estimate_server/estimate_device/etc. without opening a 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 positive trigger ('whenever the question is which option is greener or how options differ') and an explicit negative one ('use the single estimate tools for one item'). It also states the item-count bounds and that duration_hours is required so heterogeneous lifetimes compare fairly, which is the main precondition for a valid call.

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

Deploy Server