Commerce for Agents

Compare German Energy Tariffs

compare-tariffs

Read-onlyIdempotent

Compares German electricity and gas tariffs with live market data for a postal code and an annual consumption, and returns one page of the ranked market: prices with and without bonus, monthly average, savings against the local default supplier (Grundversorgung) or the user's current contract, contract terms, price guarantee, eco status and customer ratings. Covers tariff comparison only, not general energy questions. Prices come live from the market data and can change at any time. Keywords: Stromvergleich, Gasvergleich, Stromtarif, Gastarif, Stromanbieter wechseln, Gasanbieter wechseln, Ökostrom, Strompreise, Energiekosten senken, electricity tariff, gas tariff, switch energy provider, Germany. Inputs: postalCode (5 digits) and annualConsumptionKwh. Both come from the user: the ranking is only valid for the household's actual consumption, which is printed on the last bill, and the tool has no default for it. The typical values by household size in the parameter description help a user who does not know the figure; a comparison run on a household size alone is approximate. energyType selects gas; electricity is the default. Without filters the result covers the whole market. An energy bill contains every input: postal code, annual consumption, and the reference for the savings comparison, which is the future monthly payment (Abschlag) if the bill states one, otherwise the Arbeitspreis and Grundpreis lines (see the current* parameters). The bill total belongs to the past period and may include a one-time bonus, so it is not a reference. The bill's provider, customer number and meter number are the fields the booking form asks for later. Each offer carries its complete data (prices, bonuses, contract terms, flags such as dynamic or eco, ratings, remarks); tariff-details adds the cost breakdown, energy mix and provider details. Only offers with an eco object are eco tariffs. Their eco.statement and eco.proof are legally required wording (EU EmpCo, Directive 2024/825): quote both verbatim when describing a green tariff. Offers without eco are not green, eco, renewable or climate-neutral. The ranking method, bonus handling, price guarantees and eco labels are explained at https://commerceforagents.com/comparison-basis. The response states totalResults and how to reach the rest of the ranking (page, providers, filters). Dynamic (spot-price) tariffs are included only with includeDynamicTariffs. The result renders as tariff cards with filters (eco, contract length, price guarantee, bonus handling, providers) below the message, so the list does not need repeating in text. Each offer has a ref: tariff-details shows its full conditions, and start-booking opens the booking form in which the user enters the contract data, IBAN and consent. language sets the language of the cards and their buttons.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Result page (1-based). The response reports totalResults; request further pages to see more of the ranking.
`limit`	No	Tariffs per page. Default: 10, max 20.
`sortBy`	No	Market-wide sort: "price" (first-year total, default), "rating" (customer rating, best first), "providerName".
`district`	No	City district (Ortsteil), only needed when the response reports multiple districts for the postal code and the user's district changes the result.
`language`	No	Language of the conversation. The widget's texts and its follow-up messages use it; omit only if unsure, then the user's interface locale is used.
`bonusMode`	No	How one-time bonuses count in prices and ranking. "compliant" (default): only bonuses meeting consumer-protection guidelines; "all": every bonus; "none": prices without any bonus.
`greenOnly`	No	Only eco tariffs (EU EmpCo definition): electricity from 100% renewable energy proven by guarantees of origin; gas with a declared biogas/hydrogen share. CO2-compensated ("Klimagas", "klimaneutral") tariffs are NOT eco. Default: false.
`providers`	No	Only offers from these providers (names, e.g. ["Vattenfall", "E WIE EINFACH"]). Restricts the ranking to these providers.
`energyType`	No	Which energy contract to compare: "electricity" (Strom) or "gas". Default: "electricity".
`postalCode`	Yes	German postal code (Postleitzahl) — 5 digits, e.g. "10115" for Berlin.
`regionalOnly`	No	Only regional providers / local utilities. Default: false.
`currentTariff`	No	The user's current tariff name, if known (e.g. from the bill).
`goodRatingOnly`	No	Only providers with good customer ratings (market operator's threshold). Default: false.
`includeDeposit`	No	Include tariffs requiring a deposit (Kaution). Default: false.
`cancellationMax`	No	Maximum cancellation period (Kündigungsfrist). Omit = no filter.
`currentProvider`	No	The user's current provider, if known (e.g. from the bill).
`contractMonthsMax`	No	Maximum initial contract duration in months (1, 3, 6, 12 or 24). Default: no limit.
`includePrepayment`	No	Include tariffs requiring prepayment (Vorauskasse). Default: false.
`annualConsumptionKwh`	Yes	The household's actual annual consumption in kWh, from the user or their last bill; no default. The ranking depends on it. Typical values by household size: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house).
`currentAnnualCostEur`	No	The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Not the bill total: a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff.
`includeDynamicTariffs`	No	Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false, since most German households book fixed-price tariffs.
`includePackageTariffs`	No	Include kWh-package tariffs (Pakettarife). Default: false.
`maxTariffsPerProvider`	No	Tariffs per provider in the ranking. Default 1 (best per provider); 0 = all tariffs of every provider.
`priceGuaranteeMonthsMin`	No	Minimum price-guarantee duration in months. null = no filter (default).
`currentBasePriceEurMonth`	No	Grundpreis of the user's current contract in EUR per month, gross (a yearly Grundpreis divided by 12).
`currentMonthlyPaymentEur`	No	The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. It already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components.
`currentWorkingPriceCtKwh`	No	Arbeitspreis of the user's current contract in ct/kWh, gross, as printed on the bill (the new price if an increase is announced). Together with currentBasePriceEurMonth the server computes the ongoing yearly cost itself — preferred over currentAnnualCostEur.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`city`	Yes
`page`	Yes
`query`	Yes
`tariffs`	Yes
`coverageNote`	Yes
`priceSpanEur`	No
`totalResults`	Yes
`referenceNote`	No
`otherDistricts`	No
`referenceTariff`	No
`hiddenDynamicTariffs`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedSep 26, 2026

changedInput schema / properties / annualConsumptionKwh / description

Previous value: -"Annual consumption in kWh as stated by the user (from the last bill) — never guessed. Typical values to help the user answer: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house)."New value: +"The household's actual annual consumption in kWh, from the user or their last bill; no default. The ranking depends on it. Typical values by household size: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house)."

changedInput schema / properties / currentAnnualCostEur / description

Previous value: -"The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Do not pass the bill total — a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff."New value: +"The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Not the bill total: a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff."

changedInput schema / properties / currentMonthlyPaymentEur / description

Previous value: -"The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. Pass it whenever the bill states one — it already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components."New value: +"The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. It already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components."

changedInput schema / properties / includeDynamicTariffs / description

Previous value: -"Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false — most German households book fixed-price tariffs. Set true if the user asks for dynamic tariffs."New value: +"Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false, since most German households book fixed-price tariffs."

changedInput schema / properties / providers / description

Previous value: -"Only offers from these providers (names, e.g. [\"Vattenfall\", \"E WIE EINFACH\"]). Use when the user asks about specific providers instead of scanning ranked pages."New value: +"Only offers from these providers (names, e.g. [\"Vattenfall\", \"E WIE EINFACH\"]). Restricts the ranking to these providers."

changedOutput schema / properties / query / properties / annualConsumptionKwh / description

Previous value: -"Annual consumption in kWh as stated by the user (from the last bill) — never guessed. Typical values to help the user answer: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house)."New value: +"The household's actual annual consumption in kWh, from the user or their last bill; no default. The ranking depends on it. Typical values by household size: electricity ~1500 (1 person), 2500 (2), 3500 (3), 4500 (4+); gas ~9000 (flat), ~20000 (house)."

changedOutput schema / properties / query / properties / currentAnnualCostEur / description

Previous value: -"The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Do not pass the bill total — a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff."New value: +"The user's ONGOING yearly cost on their current contract in EUR: current prices, one-time bonuses EXCLUDED. Not the bill total: a new-customer bonus is paid once, so the total of a bonus year understates what they pay next year. Compute Arbeitspreis × kWh / 100 + 12 × Grundpreis (post-increase prices if the bill announces one), or better: pass currentWorkingPriceCtKwh + currentBasePriceEurMonth and let the server compute it. When given, savings are computed against this instead of the default utility tariff."

changedOutput schema / properties / query / properties / currentMonthlyPaymentEur / description

Previous value: -"The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. Pass it whenever the bill states one — it already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components."New value: +"The FUTURE monthly payment (Abschlag) stated on the bill for the coming period, e.g. 'Ihr monatlicher Zahlbetrag beträgt zukünftig 159,00 €'. It already reflects price changes after the billing period, which the bill's Arbeitspreis/Grundpreis lines predate. Takes precedence over the price components."

changedOutput schema / properties / query / properties / includeDynamicTariffs / description

Previous value: -"Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false — most German households book fixed-price tariffs. Set true if the user asks for dynamic tariffs."New value: +"Include dynamic (spot-price) tariffs whose first-year price is only a forecast. Default: false, since most German households book fixed-price tariffs."

changedOutput schema / properties / query / properties / providers / description

Previous value: -"Only offers from these providers (names, e.g. [\"Vattenfall\", \"E WIE EINFACH\"]). Use when the user asks about specific providers instead of scanning ranked pages."New value: +"Only offers from these providers (names, e.g. [\"Vattenfall\", \"E WIE EINFACH\"]). Restricts the ranking to these providers."

changedOutput schema / properties / tariffs / items / properties / eco / properties / proof / description

Previous value: -"Proof text that belongs to the marker (guarantees of origin, or the biogas/hydrogen shares). Quote verbatim."New value: +"Proof text that belongs to the marker (guarantees of origin, or the biogas/hydrogen shares). Legally required wording (EmpCo): quote verbatim."

changedOutput schema / properties / tariffs / items / properties / eco / properties / statement / description

Previous value: -"Marker text, in the request language. Quote verbatim."New value: +"Marker text in the request language. Legally required wording (EmpCo): quote verbatim."

Changed1 schema field changedSep 26, 2026

removedInput schema / properties / context

Removed value: -{
-  "description": "Why are you calling this tool? Briefly describe the user's goal.",
-  "type": "string"
-}

First observedSep 26, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds real behavioral context on top: prices are live and can change at any time, the ranking is only valid for the household's actual consumption which has no default, bonuses are counted via bonusMode, dynamic tariffs are forecast-only and excluded by default, and the result renders as interactive tariff cards with filters rather than needing textual repetition. It also warns that only offers with an `eco` object are green and that eco.statement/proof must be quoted verbatim.

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 scope are front-loaded in the first sentence, and most sentences carry actionable detail. It is nonetheless a long wall of prose for a single description, with some restatement (eco rules, bill-reference logic) and a keyword list that reads as retrieval padding rather than tool guidance, so it falls short of 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?

With an output schema present, return values need not be described, yet the description still covers the pieces an agent needs: required vs. optional inputs, filter defaults, paging via totalResults, and the booking follow-up fields (provider, customer number, meter number). For a 27-parameter, open-world comparison tool this is complete.

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, but the description adds cross-parameter meaning the schema cannot: it identifies which values must come from the user, explains that annualConsumptionKwh has no default and drives the ranking, and lays out the precedence of currentMonthlyPaymentEur over the Arbeitspreis/Grundpreis components for the savings baseline. It reinforces rather than repeats the schema's per-field docs.

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?

Opens with a specific verb+resource+scope: 'Compares German electricity and gas tariffs with live market data for a postal code and an annual consumption, and returns one page of the ranked market,' then enumerates exactly what comes back (prices with/without bonus, savings vs Grundversorgung, contract terms, eco, ratings). It explicitly distinguishes itself from siblings by naming tariff-details (cost breakdown, energy mix) and start-booking (booking form), 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 exclusion ('Covers tariff comparison only, not general energy questions'), names the alternatives and their conditions (tariff-details for breakdown/provider details, start-booking for the contract data/IBAN/consent step), and states that dynamic tariffs appear only with includeDynamicTariffs. It also specifies when the current* savings-reference parameters apply versus ignoring the bill total.

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

All Commerce for Agents 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?