Commerce for Agents

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description contributes real added context: results are census-block level rather than building-level (an accuracy caveat), the address is forwarded to the US Census Bureau Geocoder (a privacy/data-flow disclosure), results are ranked by low latency then speed, and prices carry conditions and a check date.

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

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

Front-loaded with the retrieval-friendly trigger questions, then the behavioral facts. The long enumerations of example queries and of major providers (AT&T, Verizon, T-Mobile, ...) are somewhat padded, but each clause still carries selection value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description carries the return-value burden and does so: it describes the shape of results (per-provider availability and max speeds, ranked, with starting prices and source/check date) plus coverage limits and the geocoding dependency. Given 0 required parameters, the 'address or coordinates' framing is the one remaining implicit point, but it is adequately signposted.

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

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 meaning beyond the field text: it frames address vs coordinates as interchangeable locating inputs and explains that the address is geocoded to a census block, which justifies why a street address (not just lat/lon) is accepted. The speed and technology filters are restated rather than enriched, hence not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — look up US fixed broadband provider availability and speed by address or coordinates — and the domain terms (broadband, internet providers) cleanly separate it from siblings like compare-mobile-plans, compare-vpn, and compare-esims. The returned artifact (FCC availability + max advertised speeds by census block) is named explicitly, so an agent can select it without reading the schema.

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

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

The opening list of sample questions (“what internet providers are at my address?”, “is fiber available?”, “Starlink vs cable?”) gives concrete triggers for invocation. It stops short of naming an alternative tool or stating when NOT to use it (e.g., non-US addresses are implicitly excluded only via 'US fixed broadband').

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world; the description goes further by disclosing the ranking algorithm, that each result carries a provider link and price per GB/day, that no personal data is used, and the hard limitation that phone compatibility is not checked. The one remaining gap is any statement about result count, pagination, or what happens when no package matches.

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

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

The trigger sentence is well front-loaded and the behavioral sentence earns its place, but the trailing 'Keywords: travel eSIM, eSIM for Japan, cheapest eSIM, international data plan, roaming' block duplicates the opening triggers verbatim and the supported-destination list repeats the schema's 'Supported:' list. Roughly a third of the text is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present the description need not explain return values, and it still covers the safety profile indirectly, the supported destination set, the inputs, the ranking behavior, and its key limitation. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and each parameter description already carries real semantics (defaults, exclusion rules, ISO codes, unlimited interaction). The description's 'Inputs: destination, days, optional data_gb, unlimited and providers' mostly restates the schema and adds no format or edge-case detail beyond it, so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Ranks a curated catalog of country eSIM packages ... by USD list price') plus the exact ranking rule (cheapest package per provider first, then remaining by price) and the provider set. This clearly separates it from siblings like compare-broadband and compare-mobile-plans 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.

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

Opens with a rich enumeration of user intents that select this tool ('phone data abroad', 'avoiding roaming charges', 'will my phone work in Japan', 'cheapest data for N days'), and adds explicit when-not conditions: it does not check phone compatibility and the device must be eSIM-capable and unlocked. It does not name a competing sibling tool, but the trigger set and exclusions are detailed enough to route the agent confidently.

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

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

Goes well beyond the annotations (readOnly/idempotent/openWorld=false) by disclosing data provenance (prices checked on the provider's own page), the comparison metric (12-month average per line with promo prices shown alongside), and the transparency guarantees each result carries (plan/provider coverage counts, oldest price-check date, coverage note). This is exactly the extra context annotations cannot supply.

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

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

Front-loads the core action and ranking method, then layers scope limits and inputs efficiently. The trailing 'Keywords:' list is retrieval-oriented padding that an agent gains little from, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only comparison tool with an output schema, the description covers everything an agent needs: what is compared, how it is ranked, catalog limitations, what each result reports, and the absence of location-based coverage checking. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including enums and thresholds. The description only restates the parameter list ('number of lines, and optionally data need, budget per line, prepaid or postpaid, must-have features and preferred network') without adding syntax or semantics beyond it, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (compares and ranks), a precisely scoped resource (US carrier and MVNO phone plans), and the ranking rule (cheapest first by 12-month average cost per line). This clearly separates it from siblings like compare-broadband, compare-esims, and compare-tariffs without needing their schemas.

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

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

Gives clear context on when the tool applies, including that the catalog is a curated selection rather than the whole market, and that no location is used so coverage is not checked. It does not explicitly route to or away from a sibling (e.g. tariff-details for a single plan), so it stops short of a 5.

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

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.

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.

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.

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.

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.

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.

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses substantive behavioral traits: privacy facts not confirmed on provider pages are marked 'unconfirmed', each result carries its oldest price-check date, prices are US/USD with possible local checkout differences, and no personal data is used. These are exactly the caveats an agent needs to caveat its answer to the user.

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

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

The trigger sentence is well front-loaded, but the body is a single dense run-on that repeats facts ('US-priced (USD)' vs 'Prices are US/USD') and closes with a keyword-stuffing line ('best VPN, cheapest VPN, VPN comparison...') that adds no agent-usable information. Much of the length earns its place, but the tail is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, all-optional comparison tool with an output schema present, the description covers what an agent needs: input semantics, ranking logic, data provenance and currency, geographic caveats, and the unconfirmed-fact flagging policy. Return-shape details are deferred to the output schema, which is correct.

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

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 real meaning: 'needs' filters out plans where the feature is unconfirmed (an exclusion rule not evident from the schema), and 'country' only adds a note when not US rather than changing prices. It restates checkout/term_months behavior already in the schema, so it stops short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Ranks a curated catalog of US-priced (USD) VPN plans'), names the six providers in the catalog, and defines the ranking rule (cheapest first by effective monthly cost over the preferred term including renewals). This clearly distinguishes it from siblings like compare-broadband, compare-esims and compare-mobile-plans, which cover different product domains.

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

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

It opens with an explicit trigger list ('which VPN to buy, cheapest VPN, streaming, torrenting, travel, public Wi-Fi safety, audited no-logs, avoid renewal price traps'), which maps directly onto user intents an agent will encounter. It also states scope limits: the catalog is 'a selection, not the whole market' and prices are US/USD, so the agent knows when this tool is and isn't appropriate.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this by stating it 'submits, stores and sends nothing, and takes no personal data'. It adds useful behavior beyond annotations: the form renders below the message, has a two-page flow, and there is no self-service checkout link.

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

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

The description is front-loaded with the main action and read-only behavior, and the trigger examples are useful. The trailing keyword list is somewhat redundant, but overall each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich annotations, full schema coverage, and presence of an output schema, the description covers the tool's purpose, side-effect profile, trigger phrases, form flow, language behavior, and absence of a checkout link. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both ref and language. The description adds only light reinforcement, noting ref identifies the offer and language controls the form language, but it does not materially extend the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it 'opens the booking form for one offer from a comparison, identified by its ref'. It also clarifies the tool is read-only and that the form renders below the message, which distinguishes it from siblings like book-contract or submit-switch-request.

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

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

The description gives strong when-to-use signals: example user messages ('book #2', 'switch me to this'), the card's 'Jetzt buchen' button, and the note that there is no self-service checkout link. It does not explicitly list alternative tools and when not to use them, but the usage context is clear.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true. The description adds value by stating it 'stores the request encrypted, sends the confirmation emails and returns only masked data', and that an operator later submits the contract application. This discloses side effects (email sending) and storage behavior beyond what annotations convey. No contradiction.

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

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

The description is three sentences with no fluff. The first sentence states the purpose and scope, the second gives usage context, and the third describes behavior and downstream action. Front-loaded with the core function, every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 20 parameters, nested objects, and an output schema, the description covers the essential aspects: purpose, usage scenario, side effects, and the follow-up operator action. It does not detail the output schema (which exists) or error cases, but that's acceptable. It could mention that switchType includes relocation, but the schema covers that. Overall complete enough for an agent to call correctly.

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

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

Schema coverage is 100%, so every parameter already has a description. The description only summarizes the parameter groups ('contract data, IBAN and the consents in one call') which adds minimal extra meaning. Baseline 3 is appropriate; the schema carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'files a concierge switch request for an offer from a comparison' – a specific verb (files) and resource (switch request) with context. It distinguishes itself from siblings by mentioning the relationship with start-booking and the direct-call option for autonomous clients, so an agent can tell it apart.

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

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

The description explains when to use it: either via the booking form opened by start-booking, or directly by autonomous clients that hold complete data and authorization. This implies the requirement for authorization but doesn't explicitly list alternatives or exclusions (e.g., 'do not call without an offer ref'). It also notes the operator later submits the contract application, giving flow context. Clear enough but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds real context beyond that: it names the returned content categories (price composition, price-guarantee scope, renewal/cancellation terms, deposit, energy mix, ratings) and flags the eco-tariff special case. It does not discuss rate limits or error behavior, so not a 5.

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

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

The purpose and scope are front-loaded in the first clause, and the field enumeration is compact. The trailing keyword block (German and English synonyms) is padding for search matching rather than agent guidance, which costs it a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 not be explained, yet the description still summarizes them; combined with full annotation and parameter coverage, an agent has what it needs to call it correctly. Only minor routing detail (when not to call it, or how it pairs with book-contract/start-booking) is absent.

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

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

With 100% schema description coverage, the schema already documents both `ref` (pattern, origin) and `language` (enum, default). The description's note that "texts come in the requested language" loosely reinforces the schema's narrower statement that language applies to the eco statement/proof texts – marginal added value, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Returns the full conditions of one tariff") and pins the source ("from a compare-tariffs result, identified by its ref"), which cleanly separates it from the sibling compare-tariffs lister. It even enumerates the condition categories returned, so an agent knows exactly what this yields.

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

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

The description makes the workflow dependency explicit: the ref must come from a compare-tariffs result, which tells the agent when this tool is callable. It gives no explicit exclusions or routing between further siblings (e.g., book-contract vs. tariff-details), so it stops just short of full when/when-not guidance.

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