Real-time Israeli rental listings, pricing estimates, and neighborhood intelligence across Tel Aviv and central Israel. Search 5+ deduped sources with hourly liveness, view specs, estimate fair-market rent, and explore local transit and area context directly inside your agent.
Scored across 8 tools
Most tools have clearly distinct roles: search, listing details, photos, pricing, neighborhood context, spatial lookup, and coverage. The main overlap is between coverage and neighborhood_context, both of which can return city-level registry information, though their primary purposes differ.
Names are consistently snake_case and mostly verb-led, such as search_listings, get_listing, and estimate_price. The two noun-style names coverage and neighborhood_context are minor deviations but remain readable.
Eight tools are well-scoped for a real-estate listing and neighborhood intelligence server. Each tool has a clear role, and the count avoids both thinness and bloat.
The surface covers the core read-only lifecycle: discovering places, searching listings, retrieving full details and photos, estimating prices, understanding neighborhoods, and finding nearby areas. No obvious operational gaps remain for the stated purpose.
Which Israeli cities, regional groups and localities Dorit searches, with rent/sale availability and neighborhood counts; with a city, that city's neighborhood registry (ids, slugs, names in Hebrew, English and Russian, centroids) and its named areas. Call this first when unsure how a place is named.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | A city by name or slug: returns its full neighborhood registry and its named areas. Omit for the list of cities, regional groups and localities. | |
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context the annotations don't: this is a registry lookup whose result set varies entirely on whether a city is supplied, and that it is the naming authority for the domain.
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 dense, front-loaded clauses with no filler, and the actionable routing hint comes last where it is likely to be read. The semicolon-chained sentence is heavy but every clause carries distinct 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?
With no output schema, the description does the work of describing return values in detail (registry fields, multilingual names, centroids, availability flags), which is exactly what is needed. The one loose end is "Dorit", an unexplained product name that an agent has no way to interpret.
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 city parameter's name-vs-slug and omit-for-list behavior is already documented structurally. The description restates that same split rather than adding new syntax, format or edge-case guidance, 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?
The description names the specific resource (Israeli cities, regional groups, localities and, with a city, its neighborhood registry) and enumerates the concrete payload: rent/sale availability, neighborhood counts, ids, slugs, multilingual names and centroids. It is impossible to confuse with get_listing or estimate_price.
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 this first when unsure how a place is named" gives an explicit triggering condition, and the city/no-city split is stated. It stops short of naming alternatives such as find_neighborhoods_near or neighborhood_context, so the agent must infer when to leave this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grounded rent or sale price estimate from Dorit's listing corpus: a headline figure with a low–high band, sample size and window, for a neighborhood or street subject (location + rooms) or for one listing (listing_id, which also says whether its asking price is above or below market). A refusal (insufficient_data, unsupported_market, unknown_location, needs_clarification) means there is no honest number — never replace it with a guess.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City, when the location alone is ambiguous. | |
| floor | No | ||
| rooms | No | Required with location. | |
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| location | No | A neighborhood, a street, or "street, city" — as the user named it. | |
| amenities | No | Only amenities the user stated; an omitted one neither raises nor lowers the estimate. | |
| condition | No | ||
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. | |
| listing_id | No | Price a specific Dorit listing against its market. When set, send no other field. | |
| property_type | No | Sale only: apartment, unit, garden, house, twofamily, penthouse, duplex. | |
| square_meters | No | ||
| transaction_type | No | Defaults to rent. Sale estimates run in fewer cities and also return registered sold deals for a street subject. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety (readOnly, idempotent, non-destructive, closed-world); the description adds the substantive behavior an agent cannot get elsewhere — the returned shape (headline figure, band, sample size, window) and the meaning of each refusal (insufficient_data, unsupported_market, unknown_location, needs_clarification) with a hard rule not to fabricate a number. That is exactly the kind of context 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?
Two sentences, front-loaded with the outcome and return shape before the refusal contract. It is dense with stacked parentheticals, so a scan requires careful reading, but essentially no clause is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no output schema, the description supplies the return contract and refusal taxonomy, which is the hardest part to infer. The analytics-only parameters (context, llm_model) and the amenity-neutrality rule are documented in the schema rather than the description, which is acceptable but leaves the definition slightly thin on which fields are mandatory per mode.
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 75%, so the baseline is 3, but the description adds real semantics: listing_id is mutually exclusive with all other fields, and transaction_type defaults to rent while sale estimates cover fewer cities and additionally return registered sold deals. It leaves floor, condition, property_type and city to the schema, which mostly documents them.
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 ('grounded rent or sale price estimate from Dorit's listing corpus') and enumerates exactly what comes back: headline figure, low–high band, sample size and window. It also distinguishes two operating modes (location+rooms subject vs. a single listing_id), which no sibling (search_listings, get_listing, coverage, neighborhood_context) offers.
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 two calling modes and the parameters that select them ('location + rooms' vs. 'listing_id'), and spells out the refusal codes with the explicit instruction never to substitute a guess. It stops short of naming a sibling tool to use instead (e.g. search_listings for browsing comps), so routing across the sibling set is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The neighborhood containing a place and those within walking distance of it: a station or rail line, a landmark, a campus, a mall, a street or an address, or another neighborhood. Returns neighborhood ids you can pass to search_listings. Stations that are planned or under construction are marked.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City by name or slug, when known. Narrows an ambiguous place. | |
| place | Yes | A train or light-rail station or line, a landmark, a campus, a mall, a street or street address, or another neighborhood — in Hebrew when the user wrote Hebrew. | |
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. | |
| radius_meters | No | Walking radius; defaults to 800. | |
| transaction_type | No | sale keeps bordering neighborhoods inside the cities where sale search is open. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, openWorld=true, destructive=false, so the safety profile is covered. The description adds value beyond those annotations by disclosing that planned/under-construction stations are flagged and that results are ids consumable downstream. Minor gaps remain (pagination, result ordering, radius defaults), but the added context is meaningful.
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 tightly packed sentences with no waste; the core purpose and the chaining hint are front-loaded. Nothing in it repeats structured fields verbatim or pads with filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter read-only lookup with 100% schema coverage and no output schema, the description covers what the tool finds, the accepted place types, the return shape (ids) and the planned-station marker. It leaves radius/transaction_type behavior entirely to the schema, which is acceptable, but a note on default radius or result scope would make it fully self-sufficient.
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 already carries its own documentation, making 3 the baseline. The description reinforces the accepted place types but adds no radius, transaction_type, or city semantics beyond the schema, so it doesn't exceed baseline.
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 and scope: the neighborhood containing a place plus those within walking distance, enumerating input place types (station, landmark, campus, mall, street/address, other neighborhood). It also states the output ('neighborhood ids you can pass to search_listings'), which distinguishes it from siblings like search_listings and neighborhood_context.
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?
Implies when to use: a place-based geo lookup whose output feeds search_listings, giving a clear chaining context. It stops short of naming alternatives or exclusions (e.g., when to prefer neighborhood_context instead), so it's clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details of one live Dorit listing: photos, recorded features, move-in timing, posting and re-offer timestamps, price history, and the last liveness check. A listing that was taken down or aged out of search returns only its status (taken_down or expired). Contact details and the source ad link are not exposed; the url opens the listing page on dorit.bot. Photos are listed as URLs; get_listing_photos returns them as images to look at.
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. | |
| listing_id | Yes | Dorit listing id, as returned by search_listings or found in a dorit.bot/apartment/<id> link. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations: it discloses the degraded return shape for taken_down/expired listings, states that contact details and the source ad link are redacted, explains what 'url' points to, and clarifies photos arrive as URLs rather than inline images. This is exactly the context an agent cannot get from structured fields.
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 tight sentences with no filler: return contents first, degradation case second, redaction third, then the sibling pointer for photos. Every sentence carries decision-relevant information.
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 takes on responsibility for describing the response and does so, including the partial-result case for dead listings and the format of photo fields. Nothing an agent needs to interpret the return value 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 description coverage is 100%, so listing_id, context, and llm_model are already fully documented. The description adds nothing about parameter values, which is acceptable given the schema coverage baseline of 3.
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?
Names a specific verb+resource ('Full details of one live Dorit listing') and enumerates exactly what is returned: photos, features, move-in timing, timestamps, price history, liveness check. This clearly separates it from search_listings (discovery) and get_listing_photos (image rendering), which the description names 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?
Usage is strongly implied by 'one live listing' full-detail retrieval, and the description routes the agent away from this tool for images by naming get_listing_photos as the alternative. There is no explicit 'use this when...' or exclusion for e.g. taken-down listings, so it falls 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.
Returns a live listing's photos as images to look at, up to 4 per call, so what the ad text leaves out can be checked by eye: flooring such as parquet, the kitchen and bathroom, light, condition. Defaults to the first 4; pass photo_indices for the others. Each image follows a label naming its listing and index, and a photo that could not be loaded is marked attached: false. A withdrawn listing returns only its status.
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. | |
| listing_id | Yes | Dorit listing id, as returned by search_listings or get_listing. | |
| photo_indices | No | Which photos to return, 0-based in the order get_listing lists them. Defaults to the first 4. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations covering safety (readOnly, idempotent, non-destructive), the description still adds substantial behavioral context: a 4-per-call cap, image labelling by listing and index, 'attached: false' for images that fail to load, and the withdrawn-listing edge case returning only status. These are non-obvious output/error behaviors not present in structured fields.
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, then defaults, output labeling, failure marking, and an edge case. Dense but nearly every clause carries actionable information, though the single paragraph packs several concepts that could be split for 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?
No output schema exists, so return values must be explained—and they are: images, labels naming listing and index, attached: false for failed loads, and withdrawn listings returning only status. An agent has enough to call and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters; the description adds the 4-per-call limit and default-first-4 behavior, and ties photo_indices to get_listing ordering. This goes slightly beyond the schema's own wording, warranting a bit above baseline.
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 a live listing's photos as images to look at.' This is clearly distinguishable from get_listing (data) and search_listings, and the description explains the concrete purpose (visual verification of what ad text omits).
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 default behavior ('first 4') and how to get others ('pass photo_indices'), plus the motivating use case (checking flooring, kitchen, bathroom, light, condition by eye). It stops short of explicitly naming when to use a sibling like get_listing instead, so no explicit alternative routing, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | A description of your goal and what kind of tool would help accomplish it. | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context about what invoking it does (does it return candidate tools, register them, or just log the request?) beyond the fallback hint, which is usage rather than behavior.
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 the action first and the qualifier second; every clause earns its place and there is no padding.
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?
No output schema exists, so the description should explain what a caller gets back from a tool-discovery call. It does not, leaving the main remaining gap for an openWorld meta-tool; the parameter docs partly compensate via the well-specified 'context' field.
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 both parameters ('context' and 'llm_model', including the useful 'never guess' instruction) are fully documented in the schema. The description adds no parameter meaning beyond that, 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+resource: 'check for additional tools' for tasks needing specialized capabilities. It is distinguishable from all siblings (scheduling, weather, events), but it does not say what the check actually returns or whether tools are enabled as a result.
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 trigger condition ('whenever your task might benefit from specialized capabilities') plus a non-obvious nuance ('even if existing tools could work as a fallback'), which preempts the common failure of never probing. It does not state when NOT to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a neighborhood is like: Dorit's editorial description, typical asking rents by room count, live listing count, rail and light-rail stations nearby, and bordering neighborhoods — plus a dorit.bot browse link. Without a neighborhood, returns the city's description and its neighborhood registry. Use estimate_price for a priced subject.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City by name or slug. | |
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| language | No | Language of the description; defaults to the connected user's language. | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. | |
| neighborhood | No | Neighborhood by name or slug. Omit for the city itself: its description and neighborhood list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond that: the dual output mode with and without a neighborhood, and the contents returned. It does not mention auth or rate limits, but the fallback disclosure is a useful behavioral detail.
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 dense, front-loaded sentences with no waste. The main output contents come first, followed by the fallback mode and the pricing alternative.
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 and five parameters, the description does well by enumerating the return contents and both operating modes. It could be slightly more complete about the response shape or how the city fallback differs structurally, but an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all five parameters, including the optional neighborhood and its omission semantics. The description reinforces the neighborhood omission behavior but adds no new syntax or constraint beyond what the schema provides.
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 the exact resource and enumerates its contents (editorial description, rents, listing count, stations, borders, browse link), and explicitly contrasts with estimate_price for priced subjects. An agent can tell precisely what this tool returns and which sibling handles pricing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the fallback behavior when neighborhood is omitted and points to estimate_price as the alternative for pricing. However, it does not clarify when to use this versus find_neighborhoods_near or search_listings, leaving some sibling disambiguation to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Dorit's live apartment listings (rent or sale) in Israeli cities, localities and regional groups, narrowed to neighborhoods or named areas, with structured filters: price, rooms, size, floor, move-in month, property type, roommates and features; tags for attributes Dorit reads from the ads, such as parquet or a rear-facing flat; and keywords matched literally in the listing text for anything else. Returns compact listings with dorit.bot links, newest first by default, and what the place names resolved to. Use get_listing for one listing's full details and photos.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| sort | No | newest | |
| tags | No | Short words, in any language, for an attribute of the flat no other field covers: a material, an orientation, noise, light, a view, a building detail ("parquet", "פרקט", "quiet", "דירה עורפית"). Each word resolves to one of the tags Dorit reads from listings' ad text, and from their photos once Dorit has reviewed them; a listing must carry every resolved tag. A tag is positive evidence only: a listing that has the attribute without its ad saying or showing it is not returned. The output names the tag each word resolved to, and lists a word that resolved to none in unmatched_tags without narrowing the search by it. Places, rooms, prices and the features above have their own fields. | |
| cities | No | Cities, localities or regional groups by name in Hebrew, English or Russian, or by slug ("תל אביב", "Tel Aviv", "tel-aviv", "עמק חפר"). A group covers every settlement in it. Omit when neighborhoods or search_area already say where. | |
| context | Yes | Explain in 15-25 words, in third person, why this tool is called and how it supports the user's goal. For analytics only. You MUST describe only the abstract purpose of the tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying information from the user request or tool results, including names, emails, phone numbers, IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", "the customer", or "an account". Example: "Retrieving a customer's recent orders to investigate a billing issue and help support determine the appropriate resolution." | |
| max_sqm | No | ||
| min_sqm | No | ||
| features | No | true requires the feature; false excludes it; omitted does not filter. elevator=true means an elevator or a low floor (see max_floor_without_elevator). | |
| keywords | No | Literal terms for a wish neither tags nor another field covers, or for a word tags returned in unmatched_tags ("תקרה גבוהה", "high ceilings", "נוף לים"). A listing matches when its description contains any of them (case-insensitive substring). Most listings are written in Hebrew, so include the Hebrew term and its spelling variants. Matching is literal: a listing that has the feature but does not mention it is not returned. Places, rooms, prices and the features above have their own fields and do not belong here. | |
| llm_model | Yes | The exact model identifier you (the assistant) are running as, taken from your system prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you do not know your model identifier with certainty, pass "unknown" — never guess. | |
| max_floor | No | ||
| max_price | No | ||
| max_rooms | No | ||
| min_floor | No | ||
| min_price | No | ||
| min_rooms | No | Israeli room count (whole or half rooms; a living room counts). | |
| page_size | No | Defaults to the plan's page size (10 on trial, 25 on premium). | |
| roommates | No | exclusive = only rooms in shared flats; excluded (default) = whole apartments only. | |
| handover_by | No | Sale only: latest handover month, YYYY-MM. | |
| neighborhoods | No | Neighborhoods, named areas of a city ("הצפון הישן", "מערב ראשון לציון"), landmarks or housing projects, by name, slug or the ids coverage and find_neighborhoods_near return. A neighborhood inside a listed city narrows that city to it; one in another city is added to the search. | |
| property_types | No | Asset types: apartment, unit, garden, house, twofamily, penthouse, duplex. Omit for all. | |
| entrance_months | No | Rent only: acceptable move-in months, YYYY-MM. A listing naming no month is treated as available now or within the month. | |
| transaction_type | No | rent (monthly ILS) or sale (total ILS). Sale is open in fewer cities. | rent |
| exclude_neighborhoods | No | ||
| max_floor_without_elevator | No | Highest acceptable floor when the building has no elevator; above it an elevator is required. Same as features.elevator=true with this walk-up limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real context: results are compact, carry dorit.bot links, default to newest-first, and report what place names resolved to. It also discloses the positive-evidence-only semantics of tags and keywords (a listing lacking the term is not returned), which is behavior an agent cannot infer from the 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?
A single front-loaded paragraph that leads with the verb, scope, and filter taxonomy before the sibling hand-off. It is dense but every clause carries information; mild redundancy appears where the tags explanation restates what the schema already says.
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 25-parameter, nested-object search tool with no output schema, the description covers the query model and sketches the return shape (compact listings, links, newest-first, resolved places). It omits pagination behavior and plan-based page-size limits, which the agent must learn from the schema instead.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 25 parameters and only 60% schema description coverage, the description earns credit for grouping the filter families and explaining the tag/keyword distinction with concrete examples ('parquet', 'rear-facing flat', Hebrew variants). It leaves several parameters (page, sort, price/floor ranges, property_types) entirely to the schema, so it does not fully close 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?
States a specific verb and resource ('Search Dorit's live apartment listings') and pins the scope: rent or sale, Israeli cities/localities/regional groups, narrowed to neighborhoods. It also enumerates the three filter families (structured filters, tags, keywords), so an agent can distinguish it from get_listing without reading either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to get_listing for a single listing's full details and photos, and implicitly separates tags (attributes Dorit reads) from keywords (literal text) so the agent knows which lever to pull. It does not mention the other siblings (coverage, find_neighborhoods_near) as discovery alternatives, so the routing picture is clear but not complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
