Prepare a German Energieausweis (energy certificate); an Energieberater checks and signs it.
Scored across 11 tools
Each tool mostly maps to a distinct step in the energy-certificate lifecycle, from eligibility and building lookup to ordering, document upload, review, and certificate retrieval. There is mild potential confusion between get_status and review_order, and between start_order and request_confirmation, but the descriptions clarify that one is lifecycle status vs. pre-order review, and one creates a draft vs. sends a confirmation email.
All tool names follow a consistent snake_case verb_noun pattern such as add_document, check_eligibility, find_building, get_status, and update_order. The convention is predictable throughout the set.
The 11 tools are well-scoped for a German energy-certificate ordering workflow, with each tool covering a meaningful lifecycle step. The count is neither thin nor bloated.
The surface covers the full workflow: eligibility check, building lookup, draft order creation, data updates, document uploads, status checks, inquiry answering, confirmation email, review, certificate download, and listing facts. No obvious lifecycle gap remains for the stated purpose.
Uploads a file to a draft order: an energy bill or Heizkostenabrechnung (rechnung) or a photo (street side, heating, type plate). JPG, PNG, WebP or PDF as base64, at most 10 MB, 20 files per order. Bills are read and compared with the entered consumption after the customer has ordered; the Energieberater checks the photos. Usually the customer takes the photos on our page after the confirmation email. Orders nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | rechnung (energy bill or Heizkostenabrechnung), fassade_strasse (photo of the street side), fassade_garten, heizung (photo of the boiler or heat pump), typenschild (photo of its type plate) or sonstiges | |
| filename | No | the file's name, for your reference | |
| order_id | Yes | the order_id start_order returned | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private | |
| content_base64 | Yes | the file, base64-encoded: JPG, PNG, WebP or PDF, at most 10 MB |
| Name | Required | Description |
|---|---|---|
| kind | Yes | |
| mime | Yes | |
| check | No | |
| size_bytes | Yes | |
| document_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real behavior beyond the annotations: size and count limits (10 MB, 20 per order), what happens afterwards (bills are parsed and compared to entered consumption, an Energieberater reviews photos), and 'Orders nothing', which reassures the agent this is not a committing action. It does not address what happens on re-upload of the same file despite idempotentHint=false, which is a minor gap.
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?
Four compact sentences: what it does, allowed inputs and limits, downstream processing, and the no-commit guarantee. Front-loaded and free of 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?
Given an output schema and fully described parameters, the description covers the workflow position, limits and downstream effects an agent needs to call it correctly. Only duplicate-upload behavior is unaddressed.
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 each parameter is already documented, including the kind enum values and the base64 size cap. The description reinforces the accepted formats and size but adds no semantics absent from the schema; 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 ('Uploads a file to a draft order') and immediately enumerates what a file can be (energy bill, Heizkostenabrechnung, photo types). This clearly separates it from siblings like start_order or update_order, which never accept binary content.
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?
Explains the intended context: files attach to a draft order before/around ordering, and photos are usually taken by the customer after the confirmation email. It does not name an alternative tool or state exclusions explicitly, 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.
Answers the open question (Rückfrage) about an ordered certificate with the customer's answers: values keyed by the item keys get_status listed, files the question asks for, and an explanation. Ask the customer first and send only what they confirmed.
| Name | Required | Description | Default |
|---|---|---|---|
| values | No | the answers, keyed by the item keys get_status listed; numbers with a point, e.g. 2004 or 140.5; dates as YYYY-MM-DD, months as YYYY-MM; a multiselect's option values comma-separated, keine for none; ja or nein | |
| order_id | Yes | the order_id start_order returned | |
| documents | No | files the upload items ask for, each with the item it answers | |
| explanation | No | what the customer wants to add or explain, e.g. why a value can't be given; in German | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| ordered | Yes | |
| delivery | No | |
| status_text | Yes | |
| open_inquiry | No | |
| order_number | Yes | |
| certificate_ready | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a write operation (readOnlyHint=false) that is not idempotent, so the agent knows repetition is risky; the description adds the useful constraint to collect customer confirmation before sending. However, it never says whether answering closes the Rückfrage, whether a second call replaces prior answers, or what happens on partial/invalid answers – material gaps for a non-idempotent mutation.
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?
A single sentence that front-loads the action and resource, then the payload, then the prerequisite. Every clause carries information; nothing is repeated from the title.
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?
Returns are covered by the output schema and all five parameters are fully described in the schema, so the description only needs to convey intent and the confirmation workflow, which it does. It falls short of complete by omitting post-submission effects (question closure, resubmission semantics) for a non-idempotent write.
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 value formatting, document kinds, and the order_token privacy note. The description only restates the same grouping ('values keyed by the item keys get_status listed, files the question asks for, and an explanation') without adding syntax or edge-case guidance beyond the schema, so 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 ('Answers') plus the exact resource ('the open question (Rückfrage) about an ordered certificate') and the payload it takes (values, files, explanation). This is clearly distinguishable from siblings like add_document or update_order, which do not target an open inquiry.
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?
'Ask the customer first and send only what they confirmed' gives a concrete precondition and a workflow constraint that no sibling tool states. It implies when to use this rather than add_document or update_order but never names those alternatives or says what to do if no open question exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks whether Energieausweis Express can issue a Verbrauchsausweis (consumption-based energy certificate) for a residential building in Germany, before any order exists. Returns yes or no with the reason in German (including the rule for houses with a Bauantrag before 1 November 1977 and the change on 1 January 2027), the all-inclusive price, the delivery time and what is needed. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | number of flats (Wohnungen) in the whole building, if known | |
| purpose | No | what the certificate is for: verkauf (sale), vermietung (letting), verlaengerung (lease extension), aushang (display or own records) | |
| modernised | No | parts of the envelope renewed since construction: dach (roof or top floor ceiling insulated), aussenwand, fenster, kellerdecke | |
| year_built | No | year the building was built (Baujahr), if known | |
| residential_only | No | true if the building is used for housing only; false if it also has shops, offices or practices |
| Name | Required | Description |
|---|---|---|
| note | No | |
| price | Yes | |
| needed | Yes | |
| reason | Yes | |
| delivery | Yes | |
| includes | Yes | |
| price_cents | Yes | |
| verbrauchsausweis_possible | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true and the description's 'Changes nothing' is consistent with that, so no contradiction. It adds real content beyond the annotations: a yes/no answer with a German-language reason, the specific legal rules (Bauantrag before 1 Nov 1977, change on 1 Jan 2027), price, delivery time and required documents — though some of that overlaps the output schema.
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?
One dense, front-loaded sentence followed by a short safety clause — no filler, and the purpose leads. The single sentence is long and packs output details, legal rules and price into one breath, slightly hurting scannability.
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 needn't enumerate return fields, and it still summarizes the verdict shape. The remaining gap: all five parameters are optional, and the description never says how the check behaves when information is missing — a real question for a pre-order eligibility tool.
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 five parameters (units, purpose, modernised, year_built, residential_only) are already well documented by the schema itself. The description adds nothing about how those inputs influence the verdict or how partial/unknown inputs are handled, so 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 (checks) on a specific resource (issuance eligibility for a Verbrauchsausweis for a German residential building) and adds the crucial scope 'before any order exists', which separates it from order-side siblings such as start_order or get_status. An agent can route to it without opening any 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?
'before any order exists' clearly places it at the pre-order stage, implying it precedes start_order. It gives the condition for use but does not explicitly name the alternative tools or state when not to use it (e.g. after an order exists, use get_status).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds the building at a German address in our 3D building data. Returns the building at the address first, then nearby buildings, each with a building_ref for start_order and a short German description (type, storeys, footprint). If several addresses match, returns them instead: ask the user which one is meant. Where the address may be one of several buildings (semi-detached or terraced houses, several buildings on one plot), ask the user which is theirs. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | street, house number, postcode and city, e.g. 'Buschkamp 12, 48161 Münster' |
| Name | Required | Description |
|---|---|---|
| address | No | |
| addresses | No | |
| buildings | No | |
| next_step | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and the description reinforces it with 'Changes nothing', so the safety signal is consistent. Beyond annotations it adds real behavior: result ordering (exact building first, then nearby), the presence of a building_ref usable with start_order, and a short German description containing type, storeys and footprint. It doesn't mention limits on how many nearby buildings are returned, 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?
Four sentences, front-loaded with the core action and result shape, then the two disambiguation cases. The 'ask the user' instruction appears twice, but the two cases are genuinely different (address ambiguity vs. building ambiguity), so little is wasted.
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 one-parameter lookup with an output schema and read-only annotations, the description covers what is needed: what it returns and in what order, how to handle ambiguity, and that it mutates nothing. Return-field details can be deferred to the output schema.
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 the single address parameter already carries a format example, so the schema does the heavy lifting. The description adds a small constraint by specifying German addresses, but offers no extra syntax or normalization rules. Baseline 3 is appropriate.
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 ('Finds the building') plus a clear scope: a German address in the 3D building data. No sibling tool does anything similar, and the description makes the domain distinction (German addresses only) explicit without needing 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?
Gives concrete conditional guidance: if several addresses match, ask the user which one is meant; if the address may map to several buildings (semi-detached, terraced, multiple buildings on a plot), ask the user which is theirs. It also signals the downstream purpose via building_ref for start_order. It does not explicitly name alternatives or exclusion cases, so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns download links for the issued certificate and its invoice (PDF). The links work for one hour and open nothing else, so they can be shown to the user; call again for fresh ones. The customer also got both by email. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | the order_id start_order returned | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| invoice_url | No | |
| valid_until | No | |
| certificate_url | Yes | |
| links_valid_until | Yes | |
| registration_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond the annotations: one-hour link expiry, safe-to-display semantics, and the fact the customer already received both by email. 'Changes nothing' reinforces readOnlyHint=true and is consistent with idempotentHint=false (fresh links each call). It stops short of describing failure modes for expired or invalid order tokens.
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?
Three short sentences, front-loaded with what is returned, then the expiry caveat, then the read-only reassurance. No 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?
An output schema exists, so return values need no prose explanation; parameters are fully covered by the schema. The description supplies the only non-schema facts an agent needs (expiry, shareability, no mutation).
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% and both parameters are documented there as values returned by start_order, so the baseline of 3 applies. The description adds no additional meaning about order_id or order_token handling.
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 download links for the issued certificate and its invoice (PDF). No sibling tool covers certificates, and the scope is unambiguous without opening 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?
Gives clear operational context: the links can be shown to the user, expire after an hour, and should be re-fetched by calling again for fresh ones. It does not name an alternative tool, but none of the siblings are plausible substitutes, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns what a property listing must state about the energy certificate (§ 87 GEG): type of certificate, Endenergieverbrauch, main energy carrier of the heating, year built and Effizienzklasse, as ready-to-paste German text. Only once the certificate is issued. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | the order_id start_order returned | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| text | Yes | the mandatory facts, one per line, ready to paste into the listing |
| one_line | Yes | the same in one line, for listing portals |
| year_built | Yes | |
| valid_until | Yes | |
| final_energy | Yes | |
| energy_carriers | Yes | |
| certificate_type | Yes | |
| efficiency_class | Yes | |
| registration_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false; the description reinforces this with 'Changes nothing' and adds the real behavioral constraint (certificate must already be issued) plus the shape of the returned text. It does not explain the non-idempotent hint for what is otherwise a pure read, which is the one unexplained trait.
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?
Three short sentences, front-loaded with what is returned and the enumerated fields, then the precondition, then a closing safety note. Efficient overall, though 'Changes nothing' partly restates the readOnlyHint annotation.
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 no explanation, and annotations cover the safety profile; the description still supplies the field list and the issuance precondition. It stops short of saying what happens when the certificate is not yet issued (error vs. empty), the one gap an agent would hit in practice.
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% and both required parameters (order_id, order_token) are documented in the schema, including the privacy note on the token. The description adds nothing about the parameters, 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?
Specific verb+resource: returns the § 87 GEG energy-certificate facts a listing must state, with the exact fields enumerated (type, Endenergieverbrauch, energy carrier, year built, Effizienzklasse) and the output form ('ready-to-paste German text'). It is clearly distinguishable in substance from get_certificate, but it never names a sibling or states explicitly how it differs, which keeps it at 4 rather than 5.
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?
'Only once the certificate is issued' is an explicit gating precondition that tells the agent when the call is valid and implicitly when it is not. There is no named alternative (e.g. get_certificate/get_status) for the not-yet-issued case, so the routing guidance is clear but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows where the order stands, in plain German words: prepared, ordered, being checked by the Energieberater, waiting for an answer to a Rückfrage (with its questions), issued. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | the order_id start_order returned | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| status | Yes | |
| ordered | Yes | |
| delivery | No | |
| status_text | Yes | |
| open_inquiry | No | |
| order_number | Yes | |
| certificate_ready | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to re-argue safety. It does add real context beyond them: the shape of the returned state (including that a Rückfrage state carries its questions) and the guarantee that no state is mutated. It does not mention error behavior for an invalid/mismatched token.
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?
A single front-loaded sentence with no filler; every clause does work (states, sub-state, the no-mutation guarantee). Minor cost from the informal 'in plain German words' framing, which adds little for an agent.
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 structure need not be explained, and annotations carry the safety profile. For a two-parameter read tool the description is close to sufficient; only failure modes for a wrong or foreign order_token are unaddressed.
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 both parameters are documented in the schema, including the provenance of order_id/order_token from start_order and the privacy constraint on the token. The description adds nothing about parameters, 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 ('shows where the order stands') and resource, and enumerates the exact status values returned (prepared, ordered, being checked, Rückfrage, issued). An agent can tell this is the read-only status lookup apart from update_order or review_order, though no sibling is named explicitly.
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 closing 'Changes nothing' implies a read-only lookup and the status enumeration implies 'use this to check progress', but there is no explicit statement of when to choose this over review_order or check_eligibility. Usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends the customer one email with a link to their prepared order on our website. This does NOT order or charge anything: the customer checks the data there, adds what is missing (usually photos of the street side and the heating) and orders and pays on our page themselves. Before calling it, ask the user for permission and tell them the price review_order returned and that they will get an email, e.g. 'Soll ich das für bei Energieausweis Express vorbereiten? Sie bekommen dann eine E-Mail, prüfen alles und bestellen selbst.' Needs the customer's name, the email address they gave for this order, and who orders. One email per order plus one resend (e.g. to a corrected address); the link is valid for 7 days. Afterwards tell the user to look for the email with the subject 'Ihr Energieausweis ist vorbereitet – bitte prüfen und bestellen', also in the spam folder.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | the customer's name | |
| Yes | where the link goes: the email address the customer gave you for this order. Don't put in an address from the user's profile or memory instead; if they differ, ask which one to use | ||
| orderer | Yes | who orders: eigentuemer (the owner), makler (estate agent), verwaltung (property management) or sonstige (someone else on the owner's behalf) | |
| order_id | Yes | the order_id start_order returned | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| ordered | Yes | always false: the customer orders on our page |
| sent_to | Yes | |
| next_step | Yes | |
| resends_left | Yes | |
| link_valid_until | Yes | |
| customer_still_adds | Yes | |
| message_for_customer | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say it is a non-destructive, non-idempotent, open-world write. The description goes well past them: exactly one email per order plus one allowed resend, a 7-day link validity window, no charge or order being placed, the email's subject line, and the instruction to tell the user to check spam. These are the operational constraints an agent cannot infer elsewhere.
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 action and the non-action, then prerequisites and follow-up. The verbatim German consent sentence is long but operationally purposeful; overall density is high with little redundancy, though the paragraph could be broken into shorter units.
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 no explanation. For a send-an-email tool with 5 required parameters, the description covers consent, the source of the price, delivery limits, link expiry, and post-call user guidance — nothing an agent needs 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% and the property descriptions already carry the important nuance (use the address the customer gave, not one from memory; keep order_token private). The description only restates which inputs are needed in prose, adding no format or semantics beyond the schema. 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 ('Sends the customer one email with a link to their prepared order on our website') and immediately delimits scope by saying what it does NOT do (no ordering, no charging). This distinguishes it cleanly from siblings like start_order, review_order, and get_certificate.
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 precondition ('Before calling it, ask the user for permission and tell them the price review_order returned'), names the sibling whose output feeds the consent step, and even supplies the wording for the confirmation question. It also covers the resend case, so the agent knows exactly when and how often to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shows the order's data and what it still needs before the customer can order: the open points (which field to send, and in German why), whether a Verbrauchsausweis is possible, the price, and a preliminary result once the consumption is complete. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | the order_id start_order returned | |
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| note | No | |
| hints | No | what looks odd without blocking, in German; check the values with the user |
| order | Yes | |
| price | Yes | |
| reason | Yes | |
| delivery | Yes | |
| next_step | Yes | |
| open_points | Yes | |
| price_cents | Yes | |
| preliminary_result | No | |
| ready_for_confirmation | Yes | |
| verbrauchsausweis_possible | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so "Changes nothing" largely restates them. The description does add genuine behavioral context beyond the annotations: the preliminary result only materializes once consumption is complete, and the open points come with a German-language rationale. It does not explain the mismatch with idempotentHint=false or the cost/latency of the call.
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?
A single dense sentence with the return contents front-loaded and the safety guarantee closing it. The parenthetical "(which field to send, and in German why)" is slightly awkward but carries real information about output shape.
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 described, and both parameters are fully documented in the schema. Combined with readOnly/openWorld annotations, the description leaves little for an agent to guess; only the missing routing guidance against siblings keeps it from a 5.
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% and both parameters are already documented, including that the token is order-scoped and must be kept private. The description adds nothing about the parameters, so the baseline of 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?
The description names a concrete resource (the order) and enumerates exactly what is returned: open points and the missing field, Verbrauchsausweis feasibility, price, and a preliminary result. That is far more specific than a restatement of the name and it implicitly separates this from check_eligibility and get_status. It stops short of naming the sibling it is not, so 4 rather than 5.
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?
"before the customer can order" and "Changes nothing" imply the safe pre-submission inspection use case, but no alternative is named and no explicit when-not condition is given. A reader must infer that this is the read-only inspection call and that update_order handles mutation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts a draft order for the building the user confirmed (building_ref from find_building). Orders and charges nothing. Returns order_id and order_token, which every later tool needs; the token opens only this order, so keep it private and never show it to anyone. Also returns what our 3D building model and the cadastre already say about the building (estimates the customer can correct) and the open points.
| Name | Required | Description | Default |
|---|---|---|---|
| building_ref | Yes | the building_ref find_building returned for the building the user confirmed |
| Name | Required | Description |
|---|---|---|
| order | Yes | |
| order_id | Yes | |
| next_step | Yes | |
| open_points | Yes | |
| order_token | Yes | opens only this order; keep it private |
| order_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: 'Orders and charges nothing' clarifies that non-readOnly creation carries no financial commitment, and it discloses the security-sensitive token handling ('keep it private and never show it to anyone') plus the fact that the token is scoped to this single order. It also previews what the caller will see back from the 3D model/cadastre and that customer corrections and open points are expected.
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 purpose and the precondition, and nearly every clause carries information. The third sentence is dense, packing return identifiers, token scope, privacy handling and model-derived content together, which slightly hurts scannability.
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 one-parameter creation tool with an output schema and existing annotations, nothing an agent needs is missing: prerequisite source, cost behavior, token handling, and a summary of the returned estimates/open points are all covered.
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 the single parameter is already documented, so the baseline is 3; the description adds real value by establishing provenance ('find_building returned') and the confirmation precondition, not just type information. It does not add format or validation details, hence 4 rather than 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 ('Starts a draft order') plus the exact scope ('for the building the user confirmed'), which cleanly separates it from siblings like update_order, review_order and find_building. An agent knows immediately this is the order-creation entry point.
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?
Explicitly ties invocation to a prior step: 'building_ref from find_building' for 'the building the user confirmed', so the prerequisite is unambiguous. It stops short of naming when not to use it or pointing to review_order/update_order for follow-up work, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enters or corrects data of a draft order: facts about the building, the heating, and the consumption periods as printed on the bills, in the bill's unit (kWh; m3 of gas, with the bill's Brennwert and Zustandszahl; litres of oil; kg of pellets; we convert). The consumption is always the whole building's, also when the customer owns one flat: from a Heizkostenabrechnung take the Gesamtverbrauch der Liegenschaft, never the customer's own share. Send only what you know: fields left out stay as they are, and consumption.periods replaces all periods. Synonyms such as 'Gas' or 'heat pump' are accepted. Values are marked as entered by an assistant; the customer sees and confirms them before ordering. Returns the order as it is now and the open points. Orders nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| facts | No | ||
| heating | No | ||
| order_id | Yes | the order_id start_order returned | |
| consumption | No | ||
| order_token | Yes | the order_token start_order returned; it opens only this order, keep it private |
| Name | Required | Description |
|---|---|---|
| hints | No | what looks odd without blocking, in German; check the values with the user |
| order | Yes | |
| open_points | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing partial-update semantics (omitted fields stay untouched), replacement semantics for consumption.periods, and — most valuably — that values are recorded as assistant-entered and must be confirmed by the customer before ordering. That the tool writes to a draft and commits nothing aligns with and enriches destructiveHint=false and idempotentHint=true.
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 verb and resource, then layers the highest-risk gotchas (unit conversion, whole-building consumption, partial update) in descending order of importance. Dense and slightly run-on — the middle sentences could be split — but nearly every clause prevents a real data-entry error.
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?
Covers the failure modes an agent would otherwise hit on a deeply nested, German-domain data-entry tool: unit and conversion factors, the Liegenschaft-vs-flat trap, synonym tolerance, and append-vs-replace behavior. Return values are summarized (current order plus open points) even though an output schema exists, and the non-committal framing is stated outright.
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?
Adds domain meaning the schema can't carry: server-side unit conversion (m3 gas with Brennwert and Zustandszahl, litres of oil, kg of pellets), the rule to take the building-wide Gesamtverbrauch rather than a single flat's share, and that synonyms like 'Gas' or 'heat pump' are accepted for carrier values, which matters because no parameter exposes an enum. Some of this restates nested field descriptions already present in 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?
States a specific verb and resource — "enters or corrects data of a draft order" — and the closing "Orders nothing" draws a hard line between it and siblings like request_confirmation, review_order or start_order. An agent can tell which stage of the order flow this belongs to without opening 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?
Gives clear conditions for the call (draft order, data read off bills) and an explicit exclusion of the ordering step. It does not name a sibling as the alternative for reading existing data (get_listing_facts) or for finalizing (request_confirmation), so the routing is inferable rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
answer_inquiry3 fields changedInput schema / properties / documents / descriptionPrevious value: -"files the upload items ask for"New value: +"files the upload items ask for, each with the item it answers"Input schema / properties / documents / items / properties / itemAdded value: +{
+ "description": "the key of the upload item the file answers, as get_status lists it, e.g. consumption.missing; needed where several items ask for the same kind of file",
+ "type": "string"
+}Input schema / properties / values / descriptionPrevious value: -"the answers, keyed by the item keys get_status listed; numbers with a point, e.g. 2004 or 140.5"New value: +"the answers, keyed by the item keys get_status listed; numbers with a point, e.g. 2004 or 140.5; dates as YYYY-MM-DD, months as YYYY-MM; a multiselect's option values comma-separated, keine for none; ja or nein"add_documentanswer_inquirycheck_eligibilityfind_buildingget_certificateget_listing_factsget_statusrequest_confirmationreview_orderstart_orderupdate_orderOrder official German energy certificates (Energieausweis) from chat — on invoice, 1-2 days.
Heat-pump readiness check for German single-family houses: traffic light, reasons, next step
Polish energy performance certificates: pricing, requirements, order, documents, payment link
German utility costs (Nebenkosten): city data, property tax, housing benefit, deadlines, bill check
Add one secure layer between your agents and this server.
