Commerce for Agents

Request Energy Contract (Concierge Switch)

book-contract

Destructive

Files a concierge switch request with the complete contract data in one call. Intended for autonomous agents that already hold the user's full profile, IBAN and a standing authorization; in a conversation with a person, start-booking opens a form in which the user enters these data. Commerce for Agents stores the request encrypted and an operator submits the contract application to the provider; the user receives a confirmation email at once and the provider's contract documents later. There is no self-service checkout link. Input: the ref of the chosen offer plus the contract data. Postal code and city come from the comparison; previousProvider, previousCustomerNumber and meterNumber are printed on the last energy bill. consent: true attests that the user explicitly agreed to (1) Commerce for Agents submitting the contract on their behalf, (2) the SEPA direct-debit mandate for the given IBAN and (3) the privacy policy at commerceforagents.com/privacy, either by an explicit yes in the conversation or by a standing authorization given to the agent. The response contains nextSteps for the user.

Input Schema

TableJSON Schema

Name	Required	Description
`ref`	Yes	Offer reference from a compare-tariffs result (field `ref`).
`iban`	Yes	IBAN for the SEPA direct-debit mandate, no spaces (e.g. DE89370400440532013000).
`email`	Yes	Email address — receives the booking confirmation and provider documents.
`phone`	No	Phone number (optional, some providers ask for it).
`street`	Yes	Street of the supply address (Straße).
`consent`	Yes	The user has explicitly agreed to: (1) Commerce for Agents submitting this contract on their behalf, (2) the provider's contract terms as shown by tariff-details, (3) the SEPA mandate for the given IBAN, (4) the privacy policy — and has been told the contract can be withdrawn within 14 days. True only after that agreement.
`language`	No	Language of the conversation — used for the confirmation email. Default: "de".
`lastName`	Yes	Last name (Nachname).
`birthDate`	Yes	Date of birth, ISO format YYYY-MM-DD. Energy providers require it for the contract.
`firstName`	Yes	First name (Vorname).
`moveInDate`	No	Move-in date (Umzugsdatum), ISO YYYY-MM-DD. Required for switchType "relocation", ignored for a switch.
`salutation`	Yes	Salutation (Anrede), required by the providers: "herr", "frau" or "divers".
`switchType`	Yes	"switch": changing provider at the current address (Anbieterwechsel). "relocation": moving in / first contract at this address (Umzug/Neueinzug).
`houseNumber`	Yes	House number (Hausnummer), e.g. "12a".
`meterNumber`	No	Meter number (Zählernummer, optional — printed on the meter or the last bill).
`accountHolder`	No	Account holder if different from the contract holder.
`desiredStartDate`	No	Desired contract start, ISO YYYY-MM-DD. Omit for the next possible date.
`previousProvider`	No	Current/previous energy provider. Required for switchType "switch".
`previousCustomerNumber`	No	Customer number at the previous provider (Kundennummer, optional but speeds up the switch).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`status`	Yes
`tariff`	Yes
`provider`	Yes
`nextSteps`	Yes
`requestId`	Yes
`annualTotalEur`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 26, 2026

changedInput schema / properties / consent / description

Previous value: -"The user has explicitly agreed to: (1) Commerce for Agents submitting this contract on their behalf, (2) the provider's contract terms as shown by tariff-details, (3) the SEPA mandate for the given IBAN, (4) the privacy policy — and has been told the contract can be withdrawn within 14 days. Only true after that agreement — never assumed."New value: +"The user has explicitly agreed to: (1) Commerce for Agents submitting this contract on their behalf, (2) the provider's contract terms as shown by tariff-details, (3) the SEPA mandate for the given IBAN, (4) the privacy policy — and has been told the contract can be withdrawn within 14 days. True only after that agreement."

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.9/5.0

Behavior5/5

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

Beyond the destructiveHint annotation, the description discloses the full workflow: encrypted storage, operator submission to the provider, immediate confirmation email, and later contract documents. It also details the consent requirements, including the 14-day withdrawal notice, which is critical for a binding action.

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 dense but every sentence earns its place. It front-loads the main action and intended audience before workflow details, and it groups parameter sources usefully without repeating every schema field.

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 high-stakes 19-parameter tool with a rich schema and output schema, the description covers preconditions, workflow, timing, consent, and response contents. Nothing essential for selecting or invoking the tool correctly 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 adds meaningful context beyond the schema: postal code and city come from the comparison, previousProvider/previousCustomerNumber/meterNumber are found on the last energy bill, and consent:true attests to specific legal agreements.

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 opens with a specific verb and resource: 'Files a concierge switch request with the complete contract data in one call.' It clearly distinguishes itself from sibling start-booking by stating that book-contract is for autonomous agents, while start-booking opens a form for a person.

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 explicitly states when to use this tool (autonomous agent already holds full profile, IBAN, standing authorization) and contrasts it with start-booking for conversation-driven data entry. It also names a non-option: 'There is no self-service checkout link.'

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?