Commerce for Agents

Request Energy Contract (Concierge Switch)

book-contract

Destructive

For AUTONOMOUS AGENTS ONLY that already hold the user's complete profile including the IBAN and a standing authorization. In a conversation with a human, do NOT use this tool and never collect personal data or an IBAN for a booking in the chat: call start-booking with the ref, which opens the booking form where the user enters everything themselves. Submits a concierge switch request for the selected tariff in one call: Commerce for Agents stores the request and an operator later submits the contract application to the provider on the user's behalf. There is no self-service checkout link — never promise or invent one. Input is the ref of the chosen offer plus the contract data. If you already hold all required fields (autonomous agent with the user's profile, or the user supplied them earlier), call the tool directly. Otherwise collect them from the user in their language, skipping anything already known — postal code and city come from the comparison. How you pace the questions is your call; with a human, a few short exchanges usually work better than one long list. If the user shared their energy bill earlier, take previousProvider, previousCustomerNumber and meterNumber from it instead of asking again. Before submitting: get the user's explicit agreement to three points — (1) Commerce for Agents may submit the contract on their behalf, (2) the SEPA direct-debit mandate for the given IBAN, (3) the privacy policy at commerceforagents.com/privacy — and show a short summary with the IBAN masked except the last 4 digits. consent: true is the caller's attestation of that agreement (an explicit yes in the conversation, or a standing authorization the user gave an autonomous agent). Never set it without such authorization and never fabricate any field. After the call, relay the nextSteps text. The user receives a confirmation email immediately and the provider's contract documents by email once submitted.

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. Only true after that agreement — never assumed.
`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

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

Behavior5/5

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

Beyond the annotations, the description discloses substantial side effects: the request is stored, an operator later submits the contract, the user receives confirmation emails, and there is no self-service checkout link to promise. It also clarifies consent semantics and warns against fabricating fields, adding meaningful context to destructiveHint=true.

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?

The description is long but dense and front-loaded with the most important condition: 'For AUTONOMOUS AGENTS ONLY.' Nearly every sentence carries operational weight, though a few conversational-pacing remarks could be trimmed without losing tool-critical information.

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 consequential contract-booking tool, the description covers prerequisites, the start-booking alternative, data collection and reuse, consent requirements, the masked summary, post-call steps, and what to relay. With an output schema present, the absence of explicit return-value details is acceptable.

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?

With 100% schema description coverage, the schema already documents all parameters, so the baseline is 3. The description adds value by explaining where parameter values come from—bill-derived fields, data already known from the comparison, masked IBAN in summaries—and by clarifying the consent flag as an attestation of explicit user agreement.

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 clearly states the action: 'Submits a concierge switch request for the selected tariff in one call' and positions it as the concierge path for autonomous agents. It explicitly contrasts with start-booking, which makes the tool's role unmistakable relative to the sibling tools.

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

Usage Guidelines4/5

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

The description gives explicit routing guidance: in a human booking conversation, use start-booking instead, while book-contract is for agents that already hold the profile and authorization. However, the later advice about collecting missing fields 'with a human' via a few short exchanges creates some ambiguity against the earlier ban on collecting personal data in chat, so the usage guidance is not perfectly crisp.

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?