Swiss homes to rent or buy, with walking distances, noise, sun and commute times for any address.
Scored across 18 tools
Descriptions are exceptionally detailed with distinct multilingual trigger phrases, so most tools are clearly separable. Minor overlaps remain: search vs search_listings vs search_new_builds share a discovery purpose, and property_value_range vs follow_property_value both funnel owners to the same free valuation link, which could cause misselection.
Almost all names use snake_case with a dominant verb_noun pattern (apply_for_listing, book_viewing, compare_listings, get_listing). Deviations are mild: bare verbs (search, fetch) and noun-only phrases (address_facts, area_market_facts, my_applications, upcoming_construction), but casing stays uniform throughout.
18 tools is on the heavier side but justified by the genuine breadth of the domain (search, listing detail, market data, viewings, applications, owner services, alerts, construction). Each tool maps to a plausible distinct user intent rather than padding.
Coverage is broad: discovery, listing detail, comparison, viewing booking, rental applications, purchase interest, enquiries, owner valuation/brokerage, area facts, market figures, and construction. Gaps are minor — no favorites/save-listing, and alert lifecycle beyond creation/unsubscribe is absent, but agents can work around these.
Use this for ANY Swiss address, even without a listing – «what is it like to live at …», «is it noisy», «schools/Kita/ÖV near …», «was gibt es rund um …», «quartier calme ?», «com'è la zona …»: the building (year, floors, flats, heating), public transport, everyday places within walking distance, road/rail noise, local prices and rents, construction nearby, and listings in or near the building.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Swiss street address, e.g. «Bahnhofstrasse 10, 8001 Zürich». | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds useful behavioral context by disclosing the breadth of data returned (noise, rents, nearby construction), which matters since there is no output schema. It does not mention rate limits, cost, or lookup latency.
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 primary instruction and scoping condition, then a compact enumeration of returned facts. The quadruple-language example list is somewhat bulky, but each example maps to a plausible user phrasing rather than being 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?
With no output schema, the description carries the burden of telling the agent what comes back, and it does so by listing the fact categories. An agent knows what to expect and when to call it; minor gaps remain on result format and coverage boundaries (e.g., non-Swiss addresses are implicitly out of scope).
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%: the address format example and the language enum/default/'use the user's language' rule are all already documented in the schema. The description's multilingual query examples reinforce language handling but add no syntax or format detail 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 resource (Swiss address) and enumerates exactly what facts are returned: building attributes, transit, amenities, noise, prices, construction, listings. The phrase 'even without a listing' cleanly distinguishes it from sibling tools like get_listing and search_listings.
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?
Strong trigger guidance ('Use this for ANY Swiss address') plus concrete multilingual example queries that map real user phrasings to the tool. It does not explicitly name alternatives such as area_market_facts or property_value_range, so the when-not-to-use boundary is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to apply for a RENTAL listing with the person's Heimster application profile (bewerben, sich bewerben, postuler, candidarsi). Call it directly once they confirm – if they are not signed in, the app shows the Heimster sign-in itself; if the profile or the phone check is missing, the result says how to complete it. Documents are never sent through the chat; they are shared on the Heimster application page afterwards.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Short personal note to the provider (optional). | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| listing_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnlyHint, openWorldHint, idempotentHint and destructiveHint, so safety is partly declared. The description adds real behavioral context beyond that: the app handles sign-in, missing-profile and phone-check feedback comes back in the result, and documents are not sent in chat but shared on the Heimster application page. It stops short of describing rate limits or what the result payload looks like.
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 a direct call-to-action, then handles edge cases and the document policy in order. The parenthetical multilingual keywords are somewhat noisy but the rest is efficient.
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 3-parameter mutation tool with no output schema, the description covers the confirm gate, auth handling, profile preconditions, result feedback and a policy on document sharing. It lacks any mention of return shape or failure semantics, which 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 coverage is 67%, so the schema already documents the optional message and language fields. The description adds no syntax or format detail for listing_id or language beyond the enum already present, so 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?
Specific verb (apply) plus resource (RENTAL listing) with multilingual keywords that aid retrieval. It is clearly distinguishable from register_purchase_interest, send_enquiry, and owner_enquiry.
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 says to call it directly once the user confirms and explains the not-signed-in and missing-profile/phone-check branches, so the agent knows when not to intervene. It does not compare against sibling alternatives like owner_enquiry or send_enquiry, but the condition for use is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this for market figures of a Swiss municipality, Kreis or Quartier (Mietpreise, Quadratmeterpreise, Leerstand, Landpreise; prix au m², loyers, taux de vacance; prezzi, affitti, sfitto): condominium and house prices per m², rents per m², land prices and vacancy rate, each with year, area level and source.
| Name | Required | Description | Default |
|---|---|---|---|
| place | Yes | E.g. «Zürich Oerlikon», «Kreis 6», «Winterthur». | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, idempotent, closed-world), so the bar is lower. The description adds genuinely useful context beyond them: the supported geographic granularity (municipality/Kreis/Quartier) and the shape of each returned record (year, area level, source).
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 that opens with the usage cue and then lists metrics. The multilingual parenthetical is dense but it is the tool's real vocabulary surface, so it earns its place; still, the trilingual metric list is heavier than strictly needed.
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?
There is no output schema, and the description compensates by enumerating the returned fields (prices per m², rents, land prices, vacancy rate, each with year, area level and source). Combined with annotations covering safety, an agent has enough to call this correctly; only the boundary with property-value siblings is left open.
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 both parameters are already documented, giving a baseline of 3. The description reinforces the `place` semantics by naming the area levels (municipality, Kreis, Quartier) and demonstrates multilingual support that maps to the `language` enum, but adds no format or constraint detail beyond 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+resource (market figures for a Swiss municipality, Kreis or Quartier) and enumerates the exact metrics returned: per-m² condo/house prices, rents, land prices, vacancy rate. It implicitly separates itself from property-level siblings like property_value_range by scoping to area-level aggregates, but never names a sibling 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 'Use this for...' framing gives a clear trigger condition, but there are no exclusions or alternatives. An agent cannot tell from this text whether an area-level question should go here or to property_value_range/address_facts when the query is ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to book a place at an open viewing (Besichtigung buchen, réserver une visite, prenotare una visita) – viewing ids come from get_listing. Needs name, e-mail and number of people. Signed in: booked at once; otherwise after the e-mail confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| Yes | |||
| phone | No | ||
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| listing_id | Yes | ||
| party_size | No | ||
| viewing_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly=false, idempotent=false, openWorld=true, destructive=false), so the bar is lower. The description still adds real behavioral value by disclosing the two fulfilment paths — immediate booking when signed in vs. booking after e-mail confirmation — which the annotations do not convey.
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?
Two tight sentences, front-loaded with the action and then the prerequisites and flow. The parenthetical multilingual synonyms add bulk but serve a real purpose for a multilingual real-estate 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?
For a 7-parameter, 4-required mutation tool with no output schema, the description covers the core inputs and the confirmation flow but omits the phone parameter, the purpose of listing_id, party_size limits, and what the caller receives on success or failure. Adequate but with clear gaps.
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 only 14% (only 'language' is documented), so the description must compensate. It does map 'name, e-mail and number of people' to name/email/party_size and explains where viewing_id comes from, but leaves listing_id and phone unexplained, so the gap is only partially closed.
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+resource ('book a place at an open viewing') and even provides the multilingual synonyms a user might speak. It names get_listing as the source of viewing ids, but does not differentiate itself from neighbours like apply_for_listing or register_purchase_interest, which are also booking/reservation actions.
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 gives clear context: this is for open viewings and the viewing id must come from get_listing first, and it explains the signed-in vs. e-mail-confirmation paths. It stops short of stating when not to use it versus the other enquiry/reservation siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants to compare two to four listings (vergleichen, comparer, confrontare): price, price per m², rooms, area, floor, availability, public transport, shops and schools nearby, sun score – side by side.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Listing ids from search_listings. | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the attribute set returned (price, price/m², sun score, nearby amenities), which is useful, but the 2–4 bound merely restates the schema's minItems/maxItems. Nothing about perf, pagination, or failure modes on unknown ids.
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 that opens with the trigger condition and then enumerates the comparison dimensions. The parenthetical translated keywords are slightly cluttered but serve intent matching, so waste is minimal.
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?
There is no output schema, so the description partly compensates by listing what the comparison returns. Combined with 100% schema coverage on both inputs, an agent has enough to invoke it correctly; only edge behavior (fewer than 2 or duplicate ids) 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%: ids (from search_listings) and language (default de, use the user's language) are fully documented in the schema itself. The description adds no format or constraint detail beyond what the schema already gives, 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?
Specific verb (compare) plus resource (listings), with the exact cardinality (two to four) and the full attribute set compared side by side. It is clearly distinguishable from search_listings and get_listing, which retrieve rather than compare.
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?
"Use this when someone wants to compare two to four listings" gives an explicit trigger, and the multilingual cues (vergleichen, comparer, confrontare) help match non-English user intents. No alternative tool is named or excluded, so it stops short of a full when/when-not routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants to be notified about new listings (Suchabo, Benachrichtigung, alerte, avviso): e-mails new matching listings for a place, type, rooms, price and area. Needs their e-mail (or a Heimster sign-in). Starts after the confirmation link; unsubscribe in one click.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| place | Yes | Municipality, postal code or canton in Switzerland, e.g. «Winterthur», «8004», «ZH». | |
| area_min | No | ||
| category | No | ||
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| price_max | No | ||
| rooms_min | No | ||
| property_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnlyHint false, openWorldHint true, idempotentHint false), and the description adds genuinely new context: it needs an e-mail or a Heimster sign-in, activation begins only after a confirmation link, and unsubscribe is one click. What it doesn't state is duplicate-alert behavior or any throttling, which keeps it from 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?
A single compact sentence front-loads the trigger, then the effect and prerequisites. The parenthetical multilingual synonyms are slightly dense but serve a real trigger-matching purpose, so nothing 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 an 8-parameter mutation tool with no output schema, the description supplies the essential operational facts: the notification behavior, the required contact/auth, and the confirmation-gated activation. The remaining gap is that five of eight parameters are undocumented in both schema and prose.
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 only 25% (just place and language are documented), so the description must carry more of the load. It names the filter dimensions ('place, type, rooms, price and area') but maps them loosely — 'type' is ambiguous between category and property_type — and adds no enum values, defaults, or unit guidance.
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+resource ('notified about new listings', 'e-mails new matching listings') with the filter dimensions it operates on. It implicitly distinguishes itself from one-shot siblings like search_listings by framing continuous notification, though it never names those siblings 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?
'Use this when someone wants to be notified about new listings' gives a clear trigger condition, reinforced by the multilingual synonyms (Suchabo, Benachrichtigung, alerte, avviso) that tell the agent when user phrasing maps here. No explicit when-not or named alternative, 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.
Full text of a result from search (id like «listing:» or «project:»).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds only that the return is full text (as opposed to the abbreviated results search yields), which is modest extra context; it says nothing about error behavior for bad ids or rate limits.
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 zero filler; the id format appears immediately rather than buried. It is terse to the point of being a fragment, but every element 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?
There is no output schema, and the description covers the essential return nature ('full text') plus the input grammar, which is adequate for a one-parameter read tool with complete annotations. Minor gaps remain around invalid-id behavior and whether any metadata accompanies the text.
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 0%, so the description carries the whole burden for the single id parameter, and it does so well by giving the concrete id grammar with examples ('listing:<uuid>', 'project:<slug>'). It stops short of saying where the id originates beyond 'a result from search', but the format detail is genuinely useful beyond the bare 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 concrete resource and scope: it returns the full text of a document that came from search, and the title names the verb (fetch a Heimster document). It is a noun phrase rather than a verb+resource sentence, and it never contrasts itself with siblings like get_listing or search, so it is clear but not fully differentiated.
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?
Phrasing as 'a result from search' implies the intended pipeline (call search first, then fetch with a returned id), which is useful implied usage. However there is no explicit when-to-use/when-not guidance and no statement of how it differs from get_listing, so 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.
Use this when an OWNER wants to follow their property's value over time (Wert verfolgen, monatliches Update): returns the link to the free owner valuation – after it the owner follows the value monthly in their Heimster account.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| living_area_m2 | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the actual outcome: a returned link plus the downstream monthly follow in the Heimster account, which tells the agent this is a hand-off to an external valuation flow rather than a data lookup.
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 opening with the usage trigger, with no filler. The parenthetical German terms are mild clutter but earn their place for a German-market tool matching localized queries.
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, the description correctly explains what comes back (the valuation link) and what happens next, which is the key missing piece. What remains thin – address format and area units – is the parameter gap already counted elsewhere; overall the definition is adequate for a simple 3-param read 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 only 33%: only 'language' is documented in the schema, while 'address' and 'living_area_m2' carry no explanation anywhere. The description mentions no parameters at all – not required 'address' format, not the unit/meaning of living_area_m2 – so it fails to compensate for the coverage gap.
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 gives a specific verb+resource ('follow their property's value over time') and states the concrete output ('returns the link to the free owner valuation'). It does not explicitly contrast itself with near siblings such as property_value_range or area_market_facts, but the OWNER persona and follow-over-time framing make the function clear.
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?
'Use this when an OWNER wants to follow their property's value over time' gives an explicit triggering condition and audience. It stops short of naming alternatives (e.g. property_value_range for a one-off estimate) or when-not to use it, 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.
Use this to show one listing in full (id from search_listings, a Heimster link, or «found:» for agency-website listings): photos, floor plans, description, costs, location facts, open viewings with ids, and the link. Call it before booking a viewing or applying.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Listing id (UUID). | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the return contents (including open viewings with ids) and the accepted id forms, which is real behavioral context. 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?
A single front-loaded sentence opens with the purpose before the parenthetical detail. It is dense but every clause carries information (id sources, return payload, preconditions). Slightly heavy for one sentence, keeping it below 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 no output schema, the description compensates by enumerating exactly what the agent gets back, plus valid id inputs, plus when to invoke it. Nothing needed to select and call this read-only 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, but the description genuinely enriches the `id` parameter by naming its three sources (search_listings output, a Heimster link, or «found:<id>» for agency-website listings) — meaning the bare 'Listing id (UUID)' schema does not convey. The `language` param is left to 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 uses a specific verb ('show one listing in full') and explicitly enumerates the payload — photos, floor plans, description, costs, location facts, open viewings with ids, and the link. This clearly distinguishes it from search_listings (which finds listings) and from the booking/application siblings.
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 gives concrete usage context: 'Call it before booking a viewing or applying,' tying the tool to a workflow step. It also tells the agent where the id may come from. It stops short of naming explicit alternatives or when-not-to-use conditions, so it lands at clear-context-but-no-exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks about their own applications or purchase interests on Heimster (meine Bewerbungen, Stand meiner Bewerbung, mes candidatures): status and links. Call it directly – if the person is not signed in, the app shows the Heimster sign-in itself.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Language of titles, descriptions and links (default de). Use the user's language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely non-structured behavior: it is safe to call directly and sign-in is handled by the app rather than the agent. That auth-handling detail is the main value-add, though rate limits or empty-result behavior are not addressed.
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?
Two sentences, zero filler: the trigger and scope come first, the invocation/auth note second. Every clause earns its place and 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?
For a zero-required-param read tool with a fully documented schema and no output schema, the description covers trigger, scope, and auth handling. It lightly sketches returns ('status and links') but says nothing about what an empty result means or result count, which is a minor gap rather than a blocking one.
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 the single 'language' parameter already documents its enum and the 'use the user's language' guidance. The description adds no additional meaning about the parameter, 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 resource and scope: the caller's own applications and purchase interests, returning status and links. The word 'own' plus the phrasing separates it from write-side siblings like register_purchase_interest and apply_for_listing. Multilingual trigger phrases (meine Bewerbungen, mes candidatures) add retrieval-specific disambiguation.
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 a clear usage trigger ('when someone asks about their own applications or purchase interests') and even tells the agent how to invoke it. It stops short of naming exclusions or an alternative tool for application history versus, say, listing enquiries, so it is clear context without explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when an OWNER anywhere in Switzerland wants to sell, let or value a property, or wants a broker (Haus/Wohnung verkaufen, vermieten, Makler gesucht, bewerten lassen; vendre, louer, agence immobilière; vendere, affittare): the Heimster team gets in touch within two working days and, if the owner wishes, connects an experienced local brokerage – nothing goes to a brokerage without their consent. Needs the address, the intent, name and e-mail (phone and timeframe optional). Signed in: sent at once; otherwise after the e-mail confirmation.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| Yes | |||
| phone | No | ||
| intent | Yes | ||
| address | Yes | ||
| message | No | ||
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| timeframe | No | now = within 3 months, year = within 12 months |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutation profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), while the description adds what actually happens: the team responds within two working days, no brokerage contact happens without the owner's consent, and submission is immediate when signed in but gated on e-mail confirmation otherwise. That is exactly the operational detail annotations cannot convey.
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 trigger condition, and the parenthetical phrase lists and consent/send semantics all carry information. It is dense but not padded; only the multi-language trigger list could be trimmed.
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, the description carries the return behavior itself (who contacts whom, when, and the consent boundary), which is sufficient for an 8-param lead-submission tool. Minor gaps remain around failure cases and what the confirmation e-mail flow requires of the agent.
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 only 25% (language and timeframe documented; intent/address/name/email/phone/message bare), so the description must compensate. It does state which fields are required (address, intent, name, e-mail) and marks phone and timeframe optional, but adds no format, validation, or meaning for message/intent beyond the enum labels themselves.
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 actor and intent set ('when an OWNER anywhere in Switzerland wants to sell, let or value a property, or wants a broker'), which separates it cleanly from tenant/buyer-oriented siblings like send_enquiry and apply_for_listing. The multilingual trigger phrases even anticipate how users phrase the 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?
Gives clear context for when to invoke: an owner-initiated sell/let/value/broker request. It does not explicitly name the alternative tool to use for non-owner enquiries or exclusions, so the agent must infer routing between it and send_enquiry.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when an OWNER asks what their flat or house is worth (Was ist meine Wohnung wert, Marktwert, valeur de mon bien, quanto vale): returns the link to Heimster's free owner valuation for that address (all of Switzerland, about two minutes, value after a short SMS check, with a personal cockpit). Heimster gives no figure for a specific property here; for area prices use area_market_facts.
| Name | Required | Description | Default |
|---|---|---|---|
| rooms | No | ||
| address | Yes | ||
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| living_area_m2 | No | Optional – prefills the valuation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it returns a link rather than a figure, takes about two minutes, requires an SMS check, and delivers a 'personal cockpit' — all context an agent could not infer from annotations.
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?
Single sentence, front-loaded with the usage trigger before the payoff and the sibling redirect. The stacked parentheticals (multilingual triggers, timing, SMS step) make it dense but each clause carries information, 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?
With no output schema, the description carries the return-value burden and does so by stating it returns a link, not a valuation figure — a critical expectation-setting detail. Only the rooms parameter is left unaddressed, a minor gap in an otherwise complete definition.
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 50%: language and living_area_m2 are documented in the schema, while rooms is not. The description reinforces 'that address' and the user-language intent via multilingual triggers, but adds little else about rooms or area inputs, so it roughly meets the baseline rather than compensating heavily.
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 link to Heimster's free owner valuation for a given address, with scope ('all of Switzerland') and delivery details. It explicitly distinguishes itself from area_market_facts, so an agent can route correctly without opening another 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?
Names the exact trigger ('when an OWNER asks what their flat or house is worth') and even supplies multilingual phrasings to match user intent. It also names the alternative (area_market_facts) for the area-price case, so when-not-to-use is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to register interest in a property FOR SALE with the agent (Kaufinteresse anmelden, kaufen möchten, intérêt d'achat, interesse all'acquisto). Optional: phone, a message and the financing status (unknown, self_funded, confirmed, approved). Call it directly once they confirm – if they are not signed in, the app shows the Heimster sign-in itself.
| Name | Required | Description | Default |
|---|---|---|---|
| phone | No | ||
| message | No | ||
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| financing | No | ||
| listing_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-destructive, non-idempotent, open-world write. The description adds genuine behavioral context beyond that: no separate auth step is needed because the app surfaces the Heimster sign-in itself. It does not warn that repeat calls are non-idempotent (duplicate interest records) or describe what the user sees after registration.
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 is front-loaded in the first clause, and the operational guidance follows in a compact second sentence. The parenthetical list of four equivalent intent phrases is bulky, but it plausibly earns its place for multilingual intent matching.
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 five-parameter write tool with no output schema, the definition covers purpose, trigger condition, optional inputs and the auth path. It stops short of describing the return/confirmation behavior and does not help the agent disambiguate from sibling enquiry tools, which is the main remaining gap.
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 only 20% (just 'language'), so the description carries real load by naming the optional phone, message and financing fields. However, it only restates the financing enum values already present in the schema and explains nothing about listing_id or what each optional field changes downstream.
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 specific verb ('register interest') and resource ('a property FOR SALE with the agent'), and the multilingual trigger phrases anchor the intent. It distinguishes itself from rental-oriented siblings only implicitly ('FOR SALE'), and it never names the adjacent tools apply_for_listing, send_enquiry or owner_enquiry, so the agent must infer the boundary.
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?
'Call it directly once they confirm' gives an explicit trigger condition, and the note that sign-in is handled by the app removes a prerequisite the agent would otherwise feel obliged to check. It offers no explicit when-not-to-use guidance or named alternatives among the many enquiry-type siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search over Heimster listings and new-build projects. Returns ids for fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real value by declaring that search is free-text rather than fielded, and that the response is identity-only (ids) requiring a follow-up fetch — a meaningful behavioral contract for an agent planning a call sequence.
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?
Two short sentences, zero filler, with the search scope front-loaded ahead of the return contract. It is slightly telegraphic ("ids for fetch" is clipped), which costs a point but keeps it dense and scannable.
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 single-parameter search with no output schema, the definition is functional but thin: no result limits, ranking, pagination, or empty-result behavior. The fetch handoff is covered, but an agent has no picture of what a result set looks like or how to page through it.
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?
There is one required parameter with 0% schema description coverage, so the description must compensate for the gap. It says nothing about query syntax, whether phrases/operators are supported, whether it matches location or free text, or length constraints — the single parameter remains semantically opaque.
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 (free-text search) and resource (Heimster listings and new-build projects). The scope deliberately spans both domains, which implies a cross-cutting search distinct from the narrower search_listings and search_new_builds siblings, though it never names them to make that contrast explicit.
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?
"Returns ids for fetch" implies the intended two-step workflow (search, then fetch), which is genuine usage guidance. However, it never states when to prefer this over search_listings or search_new_builds, nor when it is the wrong choice, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches homes and properties in Switzerland – to rent or buy, also by feel (ruhig, sonnig, lebendig/belebt, grün, zentral, familienfreundlich; calme, ensoleillé, animé; tranquillo, vivace) (Wohnung mieten/kaufen, Haus kaufen, WG-Zimmer, Studio; appartement à louer/acheter, maison; appartamento in affitto/in vendita; flat, apartment, house). Covers current listings on Heimster and on Swiss agency websites, with walking distance to supermarket, childcare (Kita, crèche), school, park, stop and train station; quiet locations (road/rail noise); sun score; and the door-to-door public-transport commute to the person's workplace (workplace + max_commute_min). Ask where they work when the commute matters. Filter by place, type, rooms, price and area; sort by newest or price.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| green | No | Only green, family-friendly surroundings: parks & playgrounds within 500 m (grün, im Grünen, Natur, Spielplatz; verdure; verde). | |
| limit | No | ||
| place | No | Municipality, postal code or canton in Switzerland, e.g. «Winterthur», «8004», «ZH». | |
| quiet | No | Only quiet locations: road/rail noise by day below 55 dB at the facade. | |
| lively | No | Only lively locations: many restaurants & cafés within 500 m on foot (belebt, lebendig, urban, Ausgang; animé; vivace). Use for «vivid area», «lots of restaurants», «where things happen». | |
| area_min | No | Minimum living area in m². | |
| category | No | rent (default), buy, shared_flat (WG room) or sublet. | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| new_build | No | Only units in new-build projects. | |
| price_max | No | CHF; per month for rent, total for buy. | |
| price_min | No | CHF; per month for rent, total for buy. | |
| rooms_max | No | ||
| rooms_min | No | Swiss room count, e.g. 3.5 | |
| workplace | No | Where the user works or studies (address or place) – for the commute filter. | |
| max_park_m | No | Max distance (m) to a park. | |
| max_stop_m | No | Max distance (m) to a bus/tram stop. | |
| max_school_m | No | Max distance (m) to a school. | |
| min_sun_score | No | Minimum Heimster sun score (0–100, direct sun on the building/flat). | |
| property_type | No | ||
| max_childcare_m | No | Max distance (m) to childcare (Kita) or kindergarten. | |
| max_commute_min | No | Max door-to-door minutes by public transport to the workplace (default 30). | |
| max_supermarket_m | No | Max walking distance (m) to a supermarket. | |
| max_train_station_m | No | Max distance (m) to a train station. |
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. The description does add one real behavioral fact beyond the annotations – that results span both Heimster and external Swiss agency websites – but says nothing about result volume, pagination, limits, or result freshness.
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 is front-loaded, but the description is a dense wall of text with extensive parenthetical keyword dumps in German, French and Italian that duplicate the schema's own synonym lists. Much of the middle ('ruhig, sonnig, lebendig/belebt, grün, zentral, familienfreundlich; calme, ensoleillé, animé...') does not earn its space because the parameters already carry those synonyms.
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 24-parameter, zero-required search tool with no output schema, the description adequately conveys the filter surface (place, type, rooms, price, area, commute, proximity, feel) and the data sources, and annotations cover the safety profile. Gaps remain around zero-param behaviour, default sort, and the limit cap, but nothing critical for correct invocation 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 83%, so the schema already documents nearly every parameter, including the multilingual synonym mappings (green, quiet, lively). The description's only added value is a summary of filter categories ('place, type, rooms, price and area; sort by newest or price'), which largely restates the schema. 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?
The description states a specific verb and resource ('Searches homes and properties in Switzerland – to rent or buy') and covers the feel-based and proximity filters, so the agent knows exactly what this tool retrieves. However, it never names or contrasts sibling tools such as search_new_builds or the generic search, so differentiation from neighbours is left to inference.
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?
There is one genuinely actionable usage instruction ('Ask where they work when the commute matters'), which implies the commute filter requires an extra step. Beyond that there is no explicit when-to-use / when-not-to-use guidance and no routing to alternatives like search_new_builds for new-build projects or create_search_alert for saved searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this for new-build homes (Neubau, Erstbezug, Erstvermietung, neuf, nuova costruzione): developments with available units, prices from, rooms and move-in date. Filter by place, rent/sale, rooms and maximum price.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | ||
| place | No | Municipality, canton or project name. | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| price_max | No | CHF; per month for rent, total for sale. | |
| rooms_min | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without help from the description. The description adds useful content-shape context ('prices from', 'available units', 'move-in date'), which is genuinely behavioral. It does not mention ordering, result caps, or rate behavior, so it adds some value but not rich context.
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?
Two sentences, front-loaded with the trigger phrase, followed by the filter inventory — no filler. The parenthetical synonym list is long but earns its place by enabling multilingual query matching. Structure is clean and readable.
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 6-param, zero-required search tool with no output schema, the description covers what results contain and which filters apply, and the annotations carry the safety profile. Missing niceties are pagination/limit behavior and the language default, though the latter is documented in the schema. Adequate 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 only 50%, covering place, language and price_max; type, limit and rooms_min are undocumented in the schema. The description compensates by naming place, rent/sale (type), rooms (rooms_min) and maximum price (price_max), covering the two otherwise-undocumented meaningful filters. limit and language defaults remain unexplained in the description, but language is handled by the schema and limit is trivial.
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+resource ('search' for 'new-build homes') and pins the domain precisely with developments that have available units, prices from, rooms and move-in date. The multilingual synonyms (Neubau, Erstbezug, Erstvermietung, neuf, nuova costruzione) sharpen the concept well. It stops short of naming the sibling it is not (e.g. search_listings or upcoming_construction), so an agent must infer the boundary from scope alone.
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 'Use this for new-build homes...' is an explicit when-to-use trigger with a concrete domain, which is more than implied usage. However, it names no alternatives and gives no when-not guidance — the agent is not told to prefer search_listings for resale or upcoming_construction for unbuilt projects. Clear context, but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants to contact the provider of a listing (anfragen, Kontakt aufnehmen, Besichtigung anfragen, contacter l'agence, contattare): sends the enquiry in their name. Needs their name, e-mail and a short message (phone optional). Works for Heimster listings and «found:» agency-website listings (forwarded to the agency). If the person is signed in to Heimster it is sent at once; otherwise Heimster e-mails a confirmation link first.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| Yes | |||
| phone | No | ||
| message | Yes | The user's own words, 5–2000 characters. | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| listing_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that the enquiry is sent in the sender's name, requires name/e-mail/message with phone optional, that agency-website listings are forwarded to the agency, and the key flow difference — signed-in users get immediate send, everyone else receives a confirmation-link e-mail. These are non-obvious behaviors an agent must plan around.
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 trigger clause followed by requirements, listing scope, and send flow in a compact paragraph. The parenthetical stack of translation keywords is clutter for a purely human reader, but it aids intent matching and does not obscure the core content.
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 six-parameter, non-idempotent, open-world write with no output schema, the description covers requirements, scope and the post-send flow. It omits what the agent should do with listing_id selection and the language parameter, and says nothing about failure handling.
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 only 33%, and the description compensates for the core fields by noting name, e-mail and message are needed and phone is optional. However, listing_id and the language enum are never mentioned in the description, so it only partially covers the gap.
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 enquiry in their name' to 'the provider of a listing'), and the multilingual trigger phrases plus the two supported listing types make it distinguishable from siblings like book_viewing, owner_enquiry and apply_for_listing without opening a 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?
Explicit trigger: 'Use this when someone wants to contact the provider of a listing', with clear scope for Heimster listings and 'found:<id>' agency listings forwarded to the agency. It does not name an alternative tool or state when *not* to use it (e.g. vs owner_enquiry or book_viewing), so it stops just 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.
Use this when someone asks what is being built or planned in a Swiss municipality or canton (Was wird gebaut, Überbauung, Bauprojekte, nouveaux logements en construction, cantieri): approved and ongoing residential projects with at least 3 flats from the federal building register (GWR), with size and status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| place | Yes | Municipality (e.g. «Uster») or canton code (e.g. «ZH»). | |
| language | No | Language of titles, descriptions and links (default de). Use the user's language. | |
| min_dwellings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real depth beyond that: the data source (federal GWR register), the inclusion threshold (≥3 flats), and the nature of the results (approved and ongoing projects, with size and status). It omits pagination/count behavior for limit.
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 with the usage trigger front-loaded and the parenthetical multilingual synonyms placed after the core scope. Nothing is redundant, though the long trigger list makes the sentence dense.
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, idempotent, no-output-schema tool with one required parameter, the description covers what it retrieves, from where, and under what filter. The only real omission is the behavior of the undocumented limit parameter, which is a minor gap rather than a blocking one.
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 50%: place and language are documented in the schema, while limit and min_dwellings have no descriptions. The description partially compensates by stating the 'at least 3 flats' criterion that underlies min_dwellings, but it says nothing about what limit controls or its 1–15 range. Baseline 3 is appropriate for this partial gap.
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 gives a concrete verb+resource ('approved and ongoing residential projects' from GWR with ≥3 flats), plus the returned fields (size, status). It is far more specific than a restatement of the title. It does not, however, distinguish itself from the sibling search_new_builds, which an agent could easily confuse with this tool.
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 usage trigger ('Use this when someone asks what is being built or planned in a Swiss municipality or canton') and supplies multilingual query phrasings to match against, which is directly actionable. There is no when-not guidance and no named alternative, so it stops short of routing between competing tools.
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.
follow_property_value3 fields changedInput schema / properties / emailRemoved value: -{
- "type": "string"
-}Input schema / properties / roomsRemoved value: -{
- "type": "number"
-}Input schema / requiredPrevious value: -[
- "address",
- "email"
-]New value: +[
+ "address"
+]property_value_range1 field changedInput schema / properties / living_area_m2 / descriptionPrevious value: -"Required for flats."New value: +"Optional – prefills the valuation."search_listings2 fields changedInput schema / properties / greenAdded value: +{
+ "description": "Only green, family-friendly surroundings: parks & playgrounds within 500 m (grün, im Grünen, Natur, Spielplatz; verdure; verde).",
+ "type": "boolean"
+}Input schema / properties / livelyAdded value: +{
+ "description": "Only lively locations: many restaurants & cafés within 500 m on foot (belebt, lebendig, urban, Ausgang; animé; vivace). Use for «vivid area», «lots of restaurants», «where things happen».",
+ "type": "boolean"
+}address_factsapply_for_listingarea_market_factsbook_viewingcompare_listingscreate_search_alertfetchfollow_property_valueget_listingmy_applicationsowner_enquiryproperty_value_rangeregister_purchase_interestsearchsearch_listingssearch_new_buildssend_enquiryupcoming_constructionSearch Swiss rentals & homes, housing guides/FAQs, tenant Chancen-Check and Mieter-Pool signup.
Swiss income tax by municipality, cheaper-town ranking, apartment listings and commute times.
Official Swiss data for all 26 cantons and 2,100 communes: tax, rent, health premiums, fuel, jobs.
Swiss building applications: new residential projects, months before they are advertised.
Add one secure layer between your agents and this server.
