Building data: address, use, size, height, floors, age, roof, solar panels and the businesses registered at each building.
Scored across 9 tools
The set draws deliberate boundaries: find_buildings is a single known location, search_buildings is many across an area, search_places resolves names to coordinates, and get_building takes a buildingId while find_buildings takes an address. Residual overlap remains between open_buildings, find_buildings and get_building (all three can return one building 'in full' and charge the same 1-credit open), and between analyse_roof and the roofAnalysis block inside get_building, which will occasionally mislead an agent into calling two paid tools for one answer.
Every name is snake_case verb_noun (analyse_roof, find_buildings, get_building, list_building_units, list_lead_lists, open_buildings, save_buildings_to_lead_list, search_buildings, search_places). Singular/plural tracks cardinality, which is a readable, deliberate convention rather than an inconsistency.
Nine tools is well within the sweet spot and each maps to a distinct step in the domain workflow: resolve a place, find one building, search many, open previews, read the full record, read units, analyse a roof, list lists, save to a list. No tool looks redundant, and nothing forces a single bloated mega-tool.
Building reads are thoroughly covered (identity, address, units, roof, hazards, climate, businesses), and lists can be created implicitly by name. But a lead list can only be listed by name and count — there is no tool to read which buildings a list holds, nor to remove buildings or delete a list, which is a notable dead end for the lead-generation workflow the server advertises. Coverage of the write side of workspace objects is the main gap.
Reads one building's roof from imagery, by the buildingId an earlier result gave, and returns it plane by plane (facing, pitch, area, sunshine, panels) with the panels it can carry, their capacity and yearly yield. Use for questions about one building's roof or the solar it can carry: "what is the roof like?", "how many panels fit?", "which way do the roof planes face?". It analyses one building per request; search results already carry stored solar figures. A roof already measured is returned from the record at no analysis cost; otherwise the request itself starts a new analysis. Cost: 1 credit when a new analysis measures the roof (an estimate-only result is free), plus 1 credit to open a building the workspace has not opened in the last year. status is on_record (returned from the record), analysed (a new analysis finished), running (still in progress, usually done within about 20 seconds; a repeat request for the same building joins the same run and is never charged twice) or not_analysed (nothing covers this roof yet). When the roof could not be measured, the figures are an estimate from its footprint, marked basis estimated and planesAreAssumed true. Where the roof measured took in the roofs attached to the building, it is cut to the building's outline and marked basis measured_cut_to_outline. Where an open survey measured the planes on the building, roofSurvey says how: lidar or image_matching.
| Name | Required | Description | Default |
|---|---|---|---|
| buildingId | Yes | The baseray building id (`buildingId` in an earlier result). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds substantial context the annotations cannot: the credit cost model (1 credit for a new analysis, free estimate-only, 1 credit to open a building not opened in a year), all four `status` semantics, the ~20s running duration with repeat-request deduplication, and the `basis`/`planesAreAssumed`/`roofSurvey` fallback semantics. This is exactly the extra behavioral detail an agent needs before invoking a metered tool.
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?
Information is front-loaded: purpose and return shape come first, then usage questions, then cost/status nuance. The status enumeration and basis clauses are long run-on sentences, but each clause carries real operational meaning, so the length is largely earned rather than 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?
With no output schema and a single parameter, the description carries the full burden and meets it: it names the returned plane fields, the panel/capacity/yield figures, and the discriminator fields (`status`, `basis`, `planesAreAssumed`, `roofSurvey`). Nothing an agent needs to call this correctly or interpret the response is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and there is only one parameter, so the baseline is 3. The description adds meaning beyond the schema by specifying where the value comes from ('by the buildingId an earlier result gave'), which helps an agent that has not retained the id know to pull it from a prior call.
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 ('reads one building's roof from imagery') and enumerates exactly what comes back (planes with facing, pitch, area, sunshine, panels; capacity and yield). It also distinguishes itself from siblings by noting that 'search results already carry stored solar figures', which tells the agent when the roof tool is the wrong one.
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 explicit when-to-use context with sample user questions ('what is the roof like?', 'how many panels fit?', 'which way do the roof planes face?') and the exclusion 'one building per request; search results already carry stored solar figures'. The condition selecting this tool over search/find siblings is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Looks up the building at one specific address, point (latitude and longitude) or company registration number (with its country). Use for one known location; it does not search or count buildings across an area. Takes exactly one of address, latitude+longitude, or companyRegistrationNumber+country. The nearest building comes in full in buildings: its address and postcode (and whether the address is an address record, a business listing or only the nearest road), use, footprint, floor area, height, floors, volume, dwellings, entrances, statedFacts (what its record states: construction year, floors, areas, units, declared use and more, where known), flood zone, seismic risk and the earthquakes on record nearby, solar potential, whether solar panels are already on the roof (from a register of solar installations at the address, with their power and battery storage, or a dated photo), and the businesses registered at the address with their largest stated size and turnover. Each figure carries its basis: measured, stated or estimated. The other buildings found there come in nearby as free previews (sizes as ranges, no house number, businesses or record), unless the workspace has already opened them. Cost: 1 credit to open the nearest building when the workspace has not opened it in the last year; previews are free.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many buildings to return, nearest first. Default 3. | |
| address | No | A street address with the town, e.g. "Bulevardul Eroilor 10, Brașov". | |
| country | No | Country of the company registration number: RO, CZ or DK. | |
| latitude | No | Latitude of the point, WGS84. | |
| longitude | No | Longitude of the point, WGS84. | |
| radiusMeters | No | How far from the point or address to look, in metres. Default 40. | |
| companyRegistrationNumber | No | A Romanian CUI (e.g. "RO14399840" or "14399840"), a Czech IČO (e.g. "00216305") or a Danish CVR number (eight digits, e.g. "24256790"); finds the building the business is registered at. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description discloses important behavior: the nearest building is returned in full, nearby buildings are free previews, and opening an unopened building costs 1 credit. It also explains the `basis` labeling for figures, which is valuable behavioral 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?
The purpose and key constraint are front-loaded, and the detailed return-value enumeration earns its place because there is no output schema. The paragraph is dense but organized, with only minor verbosity in the long list of returned fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, full schema coverage, and no output schema, the description is complete: it covers input modes, return contents, preview behavior, and credit cost. An agent has enough information to choose and invoke the tool 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 parameter syntax is already well documented. The description adds meaningful invocation semantics not expressible in the schema: exactly one of address, latitude+longitude, or companyRegistrationNumber+country must be supplied.
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 and resource: it looks up the building at one address, point, or company registration number. It explicitly scopes the tool to one known location and rules out area-wide search/count use, which distinguishes it from siblings such as search_buildings.
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 clearly says when to use this tool: for one known location, and explicitly says it does not search or count buildings across an area. It also states the mutually exclusive input modes, though it does not name the alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every fact baseray holds on one building, by the buildingId an earlier result gave, as the baseray app's building panel shows it. Use for questions about one building already found; it does not find a building by address. It holds statedFacts, what the building's record states (declared use, construction year, floors, built and floor areas, units, cadastral number, where known); parts, what a building drawn from parts is made of: each construction the register records (by its label) and each structure it does not, with its area and what its outline traces (walls at ground level or a roof from above); addresses, every address of the building (each entrance of a block with the dwellings behind it, a corner building's second street) and whether its records agree on the number; units, the units and dwellings its record lists, floor by floor and kind by kind (dwellings, shops, parking, storage), against the totals the record states, the entrances they are reached by and the dwellings the record counts behind each entrance (the units themselves are listed separately); recordSheet, the identity numbers its record carries (cadastral or property number, where the record keeps one; a land book number only as filed in the register, unverified and often an old paper land book's, never the land book in force) and every other fact on record, by section as its register lays it out (such as use, areas, storeys, construction, heating and utilities, energy certificate, accessibility); roofAnalysis, the analysed roof plane by plane (facing, pitch, area, sunshine, panels) with the panel its layout assumes; record, the roof (shape, eave height, 3D model, CO2 the solar potential would save, the roof photo's analysis date and resolution), the local climate (coldest and hottest day, frost and hot days, rainfall, for the last complete year, the recent years' average and this year so far; heating degree-days against the climate normal; the warming trend), gas and district-heating network evidence from the locality down to the building, and the heating estimate. Sizes carry their basis: measured, stated or estimated. The heating figures are model estimates, never metered values, given as two figures. The standard need, full heating at standard conditions, says whether it is checked, modelled or the building's own documented assessment: the annual heat need for space heating of the building as built (in total, per m² of heated floor area and per dwelling) and the energy the heating takes in for it, a low/high span of the need where the number of floors or the construction year is not on record, the need under each construction period where the construction year is not on record and, where a check of the model against reference buildings it was not fitted on measured its error, the band 8 in 10 of them fell in and what they were checked against. The expected use, typical heating for its heating type, occupied, is always modelled and never banded: the energy a typical occupied home like this one takes in for heating, its range over the storeys, eras and heating types it may have and how homes like it are heated in its area. Beside them: the heat in the hot water (separate from space heating), the peak heat load with the outdoor temperature it is worked out at and heat-pump electricity per performance factor. It also lists the businesses whose registered office is at its address, with their registration numbers, stated sizes, legal forms, whether a business is a person's (a sole proprietorship or an estate) and whether their register protects them from direct marketing, and the credits their registers require. A registered office is not proof that the business owns or occupies the building. Cost: 1 credit to open a building the workspace has not opened in the last year; free once opened.
| Name | Required | Description | Default |
|---|---|---|---|
| buildingId | Yes | The baseray building id (`buildingId` in an earlier result). | |
| includeRegisteredBusinesses | No | Whether to list the businesses registered at the building's address. Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the readOnly/idempotent annotations by disclosing the credit model ('1 credit to open a building the workspace has not opened in the last year; free once opened'), warning that heating figures are modelled estimates never metered values, that land book numbers are unverified register filings, and that a registered office does not prove ownership or occupancy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and cost are front-loaded, but the middle is a single enormous semicolon-chained paragraph acting as a return-value dictionary. With no output schema the content is largely justified, yet the lack of structure (no list, no grouping, run-on clauses within `parts`, `recordSheet`, `roofAnalysis`) makes it hard to scan for the one field an agent needs.
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 carries the return shape, and it does so thoroughly: field groups, size bases, heating-model caveats, business-list caveats, and the cost rule. An agent knows what it will receive and what the call costs before invoking 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?
Schema coverage is 100%, so buildingId and includeRegisteredBusinesses are already documented. The description confirms the id should come from 'an earlier result' and mentions the registered-businesses content, but never says the boolean toggles that content or what the default is — baseline 3 for a schema that does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource ('Returns every fact baseray holds on one building') scoped to a single buildingId, and explicitly excludes the adjacent operation ('it does not find a building by address'), which cleanly separates it from find_buildings/search_buildings.
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 for questions about one building already found; it does not find a building by address' gives a clear when-to-use and a when-not, plus the prerequisite that the id must come from an earlier result. It stops short of naming the sibling tools to use instead (find_buildings, search_buildings), so routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the units inside one building, by the buildingId an earlier result gave, as the building's record lists them: flats, shops, parking spaces and storage, each with its number, name or door, its floor as the record words it and as a kind and number, and its entrance, kind, use, area, rooms and cadastral number where the record states them. Use for questions such as which floor a flat is on ("which floor is apartment 275?"), which units are on a floor or behind an entrance, or the whole unit list. unit finds units by their number or name; without it the list comes a page at a time. listIsComplete is false when the record states a total of units or dwellings that differs from its list: a unit missing from the list may then still exist. A building with no units listed has unknown units, never none. The building's own facts are not part of this result. Cost: 1 credit to open a building the workspace has not opened in the last year; free once opened.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | The number or name of one unit to find, e.g. "275", "12A" or "Parcare 3". Leave out to list every unit. | |
| limit | No | How many units to return, 1 to 500. Default 200. | |
| offset | No | How many matched units to skip, to read the next page. Default 0. | |
| buildingId | Yes | The baseray building id (`buildingId` in an earlier result). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds crucial behavioral context beyond annotations: pagination behavior, the meaning of `listIsComplete`, the 'unknown units, never none' semantics for empty buildings, and a cost model (1 credit to open a building not opened in the last year, free otherwise). This is rich disclosure that an agent could not infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then use cases, then pagination behavior, then completeness caveats, then cost. Every sentence carries useful information, but the length is substantial and some phrasing (e.g., 'as the record words it') could be tightened. Still, it is well-structured and not verbose for the amount of information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given readOnly annotations and no output schema, the description covers all an agent needs: when to use, what is returned, pagination, completeness semantics, and cost. It explicitly states that the building's own facts are not part of the result, preventing scope confusion. Nothing essential 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 schema already documents each parameter thoroughly, including examples for `unit`. The description reiterates the `unit` parameter's function and pagination via `limit`/`offset`, but adds no new semantic detail beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Lists the units inside one building') and specifies the required identifier source ('by the buildingId an earlier result gave'), distinguishing it from sibling tools like get_building or find_buildings. It also enumerates what is returned, making the tool's scope unmistakable.
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 names use cases ('which floor is apartment 275?', which units are on a floor or behind an entrance) and contrasts with the `unit` parameter behavior ('`unit` finds units by their number or name; without it the list comes a page at a time'). It also warns when the list may be incomplete via `listIsComplete` and clarifies 'unknown units, never none' for empty buildings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the lead lists in the user's baseray workspace, most recently changed first, each with its id, name, how many buildings it holds, when it last changed and a link to it in the baseray app. Use to show the user's lists or to find the id of an existing list to save buildings into. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many lists to return, 1 to 50. Default 20. | |
| nameContains | No | Keep only lists whose name contains this text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds value beyond them: deterministic ordering, the fields returned per list, and that the call is 'Free' (a cost signal agents cannot infer from annotations). It does not discuss pagination behavior beyond limit, leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with zero filler, and the most important information (what is listed, ordering, returned fields) is front-loaded before the usage hint.
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 responsibly enumerates the returned fields (id, name, building count, last-changed, app link) and the ordering, so an agent knows what it will get back. Minor omissions remain around pagination/empty-result behavior, but the core is well covered for a simple two-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 coverage is 100%, so both limit and nameContains are fully documented in the schema, which establishes a baseline of 3. The description adds no syntax, range, or matching semantics beyond what the schema already states (e.g., it never mentions nameContains or its substring behavior).
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 ('Lists the lead lists in the user's baseray workspace') plus scope details: ordering (most recently changed first) and the exact fields returned. It also implicitly separates itself from save_buildings_to_lead_list by noting it is for finding an id to save buildings into.
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 explicit usage context: 'Use to show the user's lists or to find the id of an existing list to save buildings into,' which routes the agent from save_buildings_to_lead_list. No explicit when-not or exclusion conditions are stated, 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.
Opens buildings chosen from previews (search rows with locked true, or the nearby rows of an address lookup) and returns each in full: address with its house number and postcode, use, footprint, height, floors, volume, floor area, each with its basis (measured, stated or estimated), construction year, dwellings, natural hazards, solar potential, the existing-panels verdict, and the registered businesses' count, largest stated size and turnover. Use for the buildings the user picked ("open the top five", "these three"). Cost: 1 credit per building the workspace has not opened in the last year, charged all or nothing; a building already opened is free. One building's whole record (every address, units, record sheet, roof, climate, businesses by name) is not part of this result.
| Name | Required | Description | Default |
|---|---|---|---|
| buildingIds | Yes | The baseray building ids to open, 1 to 25 (`buildingId` in earlier results). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations by disclosing the billing model: 1 credit per building not opened in the last year, charged all-or-nothing, with already-opened buildings free. That cost/effect disclosure is exactly the kind of context annotations cannot carry. It omits response-format and partial-failure behavior, but the cost rule is the material risk here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action and source of ids, then the return contents, then cost - a sensible order with no filler sentences. The mid-sentence enumeration of every returned field is long and dense, but with no output schema present it largely 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?
With no output schema, the description correctly compensates by listing the returned fields and `basis` values, and it discloses the credit cost, idempotency behavior, and an explicit scope exclusion. It is nearly complete; only the relationship to the get_building sibling for full single-building records is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `buildingIds` parameter is already self-documented with its 1-25 range. The description adds provenance (ids come from locked search rows or nearby address-lookup rows) but no syntax, deduplication, or ordering semantics, so the added value over the schema is modest. 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?
Starts with a specific verb+resource ('Opens buildings') and pins down the exact input provenance (search rows with `locked` true, or `nearby` rows of an address lookup) and the full return payload. It also carves out an explicit boundary ('One building's whole record ... is not part of this result'), which lets an agent separate it from the bulk search and single-record 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?
Gives a clear usage trigger with quoted user phrasing ('open the top five', 'these three') and names where the ids must come from, which is real routing guidance. It stops short of naming an alternative tool (e.g. get_building) or stating when not to use this one, so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saves buildings into a lead list in the user's baseray workspace, where they can be worked in the baseray app. Use when the user asks to save, add or export buildings to a list. Takes the buildingIds and either the id of an existing list or a name for a new list. Saving a building already on the list changes nothing, and nothing is removed. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| leadListId | No | The id of an existing lead list to add to. | |
| buildingIds | Yes | The baseray building ids to save, 1 to 100. | |
| newListName | No | A name for a new lead list to create with these buildings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description reinforces this by noting that re-saving changes nothing and nothing is removed, which is useful for an agent worried about duplicates. The addition of "Free" is genuine cost transparency not captured in annotations. It does not describe what is returned (e.g., a new list id), which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action and destination, followed by trigger conditions, input shape, idempotency note, and cost. Every sentence carries information and the one-word "Free." is maximally 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 with no output schema, the description covers destination, trigger, inputs, and idempotency. The remaining gap is the absence of any statement about what the call returns (e.g., the created list's id), which an agent would otherwise have to discover empirically.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by framing leadListId and newListName as alternatives ("either the id of an existing list or a name for a new list") — a relationship the schema itself never states. It also confirms buildingIds is the primary input.
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 (saves), resource (buildings), and destination (a lead list in the user's baseray workspace), which cleanly separates it from siblings like list_lead_lists, find_buildings, or get_building. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use when the user asks to save, add or export buildings to a list" gives explicit trigger conditions, and the description clarifies the two routing modes (existing list id vs. new list name). It stops short of naming an alternative tool or stating when not to use it (e.g., vs. list_lead_lists), so it falls just under full marks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds, counts and ranks buildings across an area: a place name, a bounding box (at most about a county) or a circle around a point (near, up to 50 km). Use for questions about many buildings, such as lead generation, underwriting, market sizing or prospect lists: "industrial buildings over 2,000 m² with a registered business", "apartment blocks without solar panels", "houses with a registered solar installation and no battery", "buildings in the 1-in-100-year flood zone", "panel blocks built before 1990", "buildings within 2 km of a point with at least 5 registered businesses", "largest roofs for solar in a city". It does not look up a single address. Filters: category or granular building type, size (footprint, height, volume, floors, dwellings), the year built (as a building register states it), wall-panel construction, flood zone, seismic risk class, solar potential, existing panels (seen in the roof photo, or a solar installation registered at the address, with its power and battery storage), and the businesses registered at the address (how many, name, size, turnover). Returns the total that match and one ranked page of buildings; offset pages further. Searching is free. A building the workspace has already opened comes in full (locked false): address, postcode, use, sizes with their basis (measured, stated or estimated), construction year, dwellings, natural hazards, solar potential, existing panels (the settled answer, the photo verdict and what a register states of an installation at the address) and the registered businesses. Every other row is a free preview (locked true): street without its number, locality, use, each size as the range it lies in (atLeast, below), natural hazards, existing panels and how many businesses are registered there. Opening a previewed building in full costs 1 credit, once a year per building.
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Keep buildings whose centre lies within radiusMeters (1 to 50,000) of this WGS84 point. Give it instead of place or boundingBox to search just the circle; given with either, the circle must lie wholly inside that area. | |
| limit | No | Buildings per page, 1 to 25. Default 10. | |
| place | No | The area to search, as a place name: a county, city, town or district, e.g. "Ilfov", "Cluj-Napoca", "Praha 5". | |
| offset | No | Buildings to skip, for the next page. At most 500. | |
| sortBy | No | Ranking, largest first: volume, outline area, height, the largest stated employee count of a registered business, or the largest latest turnover of a registered business (in turnoverCurrency). Default volume. | |
| minFloors | No | Minimum number of floors, where floors are on record. | |
| categories | No | Keep only these building categories. | |
| floodZones | No | Keep buildings in any of these flood zones of an official flood hazard map, named by the return period of their flood ("100_year_climate_change" is the 1-in-100-year flood of the climate the map projects). A building whose zone is unknown matches none, so an empty result is not evidence of low flood risk. | |
| boundingBox | No | The area to search as WGS84 bounds, instead of place. | |
| maxYearBuilt | No | Keep buildings standing by this year, as a national building register dates them: completed in or before it (constructionYear), or dated by a census period that ended by then (completedByYear). A building with no year on record never matches, so an empty result says nothing about age. | |
| minDwellings | No | Minimum number of dwellings, where known. | |
| minYearBuilt | No | Keep buildings completed in or after this year, as a national building register states it (a row's constructionYear). A building the register dates only by a census period (completedByYear) never matches, nor does one with no year on record, so an empty result says nothing about age. | |
| buildingTypes | No | Keep buildings of any of these granular types, combined with categories by OR, e.g. "office", "warehouse", "school", "apartments", "garage". | |
| solarPresence | No | Keep buildings whose settled solar answer (a row's existingSolarPanels.presence) is any of these. Use ["registered", "detected"] for buildings that have solar panels and ["none_seen"] for roofs a photo shows empty with no installation registered. "registered_at_address" is an installation registered at an address the building shares with others, not a yes for it; "unknown" is neither a register entry nor a usable photo. | |
| minHeightMeters | No | Minimum height in metres. | |
| registeredSolar | No | true keeps buildings at whose address an official register of solar installations states one (a row's existingSolarPanels.registered). false keeps buildings no register states one for, which says nothing of their roofs: panels may be off the grid, or registered under an address written otherwise, so never report those buildings as being without solar. Leave it out to keep both. | |
| turnoverCurrency | No | The currency of the turnover bounds and of the turnover ranking: RON for Romanian businesses, CZK for Czech ones. Required with either. | |
| seismicRiskClasses | No | Keep buildings an official list of technically assessed buildings gives any of these seismic risk classes: RsI (the highest risk) to RsIV, the older urgency classes U1 to U3, or "consolidated". A building on no list matches none, which says nothing of its risk. | |
| existingSolarPanels | No | Keep buildings whose roof photo alone shows this verdict (existingSolarPanels.verdict), whatever a register states: "none_seen" keeps a building with a registered installation its photo does not show. Prefer solarPresence for whether a building has panels. Buildings never checked are excluded. | |
| minSolarCapacityKwp | No | Minimum rooftop solar capacity in kWp. | |
| onlyMeasuredVolumes | No | Keep only buildings whose volume comes from a measurement of the building itself (a survey, or a surface model measured over its roof), not from an assumed height. | |
| excludeSolarPresence | No | Leave out buildings whose settled solar answer is any of these, e.g. ["registered", "detected"] for buildings not known to have panels (which keeps the unchecked ones). Never an answer solarPresence keeps. | |
| maxVolumeCubicMeters | No | Maximum volume in m³, where known. | |
| minRegisteredSolarKw | No | Keep buildings with at least this much installed solar power, in kW, registered at the address, counting the installations that state theirs (so a row can match while its installedPowerKilowatts, given only for a whole sum, is null). A building with no registered installation, or none stating its power, never matches. Not with registeredSolar false. | |
| minVolumeCubicMeters | No | Minimum volume in m³, where known. | |
| hasRegisteredBusiness | No | Keep only buildings with at least one active business registered at the address. | |
| registeredSolarStorage | No | Among buildings with a registered solar installation: true keeps those the register states store energy (a battery), false those it states store none. A building whose register does not say matches neither. Not with registeredSolar false. | |
| minRegisteredBusinesses | No | Keep only buildings with at least this many active businesses registered at the address (a row's registeredBusinesses.count). | |
| onlyWallPanelConstruction | No | Keep only buildings a national building register states are built of wall panels: prefabricated concrete panel construction, as in panel apartment blocks. This is read for Czech buildings only, so no Romanian building matches; a building whose construction is not on record never matches, so an empty result says nothing about how a building is built. | |
| minFootprintAreaSquareMeters | No | Minimum outline area in m²: the ground footprint where the outline is drawn at the walls, larger where it is drawn at the roof's edge. | |
| maxRegisteredBusinessTurnover | No | Keep buildings whose registered businesses' latest turnover on record is at most this, in turnoverCurrency. | |
| minRegisteredBusinessTurnover | No | Keep buildings with a registered business whose latest turnover on record is at least this, in turnoverCurrency. A business with no turnover on record never matches. | |
| minRegisteredBusinessEmployees | No | Keep buildings with a registered business stating at least this many employees. | |
| registeredBusinessNameContains | No | Keep buildings where a registered business's name contains this text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover read-only/idempotent/closed-world, but the description adds the economics and access model that matter operationally: searching is free, every non-opened row is a locked preview with masked street number and ranged sizes, and opening one costs 1 credit once per year per building. It also spells out the full/unlocked payload versus the preview payload, which no annotation conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and area scoping are front-loaded, then usage, then filters, then return shape and cost — a sensible order. The seven-example list is long and partly decorative, and the returns paragraph repeats filter vocabulary, but every other sentence carries real decision-relevant 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 34-parameter, no-output-schema tool this is unusually complete: it explains the total-plus-one-page return, offset paging, the locked/unlocked row distinction, and which fields appear in each case. An agent can plan a search, page it, and anticipate cost without any further documentation.
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% across 34 parameters, so the baseline is 3, but the description adds orientation value by grouping the filter families (category/type, size, year built, wall panels, flood zone, seismic, solar, businesses) and restating the area-option constraint that bbox should be at most county-sized and circles up to 50 km. It adds context rather than syntax, so it does not exceed 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?
Opens with a precise verb+resource+scope: 'Finds, counts and ranks buildings across an area', and immediately bounds the area forms (place name, county-sized bbox, 50 km circle). It explicitly rules out the neighbouring case with 'It does not look up a single address', which separates it from get_building/find_buildings without the agent opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use contexts (lead generation, underwriting, market sizing, prospect lists) backed by seven worked example queries, plus one explicit exclusion (single-address lookup). It stops short of naming alternatives — find_buildings, get_building, search_places or open_buildings are never mentioned, so the agent must infer the routing itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds a place by name (a city, district, street or full address) and returns up to six matches, best first, each with coordinates and, for areas, a bounding box. Use to get the coordinates or the area of a place for a building lookup or an area search. It finds places only in the countries baseray holds buildings for; a place in another country returns no match, and that country can be requested at https://baseray.ai/countries.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The place to find, as a person would write it, e.g. "Cluj-Napoca", "Strada Memorandumului 28, Cluj-Napoca" or "Brno-střed". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing the result cap (up to six), result ordering (best first), per-result contents (coordinates, plus a bounding box for areas), and the failure mode for unsupported countries. The openWorldHint=false annotation is consistent with the stated country restriction, so nothing is contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose and output shape first, then intended use, then the coverage constraint. No filler and no repetition of schema or annotation 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 and a single parameter, the description carries the return-value burden itself and does so: count, ordering, and per-item fields are all specified, and the coverage limitation plus remediation URL closes the main operational 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 coverage is 100%, so the baseline is 3, but the description adds real meaning by characterising what counts as a query (city, district, street, or full address as a person would write it), which sets expectations for matching behaviour beyond the schema's example strings. No format or length detail is added, so it does not reach 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Finds a place by name') plus the accepted input taxonomy (city, district, street, full address), and clarifies it is not the same thing as building search by routing the output toward 'a building lookup or an area search'. An agent can distinguish it from search_buildings, find_buildings, and get_building 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?
Gives clear context ('Use to get the coordinates or the area of a place for a building lookup or an area search') and a hard exclusion: places outside baseray's building coverage return no match, with a URL for requesting a country. It does not explicitly name sibling tools or say when to prefer one lookup path over another, so it falls just short of a full when/when-not/alternatives statement.
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.
search_buildings2 fields changedInput schema / properties / minFootprintAreaSquareMeters / descriptionPrevious value: -"Minimum ground footprint in m²."New value: +"Minimum outline area in m²: the ground footprint where the outline is drawn at the walls, larger where it is drawn at the roof's edge."Input schema / properties / sortBy / descriptionPrevious value: -"Ranking, largest first: volume, ground footprint, height, the largest stated employee count of a registered business, or the largest latest turnover of a registered business (in turnoverCurrency). Default volume."New value: +"Ranking, largest first: volume, outline area, height, the largest stated employee count of a registered business, or the largest latest turnover of a registered business (in turnoverCurrency). Default volume."find_buildings3 fields changedInput schema / properties / companyRegistrationNumber / descriptionPrevious value: -"A Romanian CUI (e.g. \"RO14399840\" or \"14399840\") or a Czech IČO (e.g. \"00216305\"); finds the building the business is registered at."New value: +"A Romanian CUI (e.g. \"RO14399840\" or \"14399840\"), a Czech IČO (e.g. \"00216305\") or a Danish CVR number (eight digits, e.g. \"24256790\"); finds the building the business is registered at."Input schema / properties / country / descriptionPrevious value: -"Country of the company registration number: RO or CZ."New value: +"Country of the company registration number: RO, CZ or DK."Input schema / properties / country / enumPrevious value: -[
- "RO",
- "CZ"
-]New value: +[
+ "RO",
+ "CZ",
+ "DK"
+]search_buildings1 field changedInput schema / properties / floodZones / items / enumPrevious value: -[
- "5_year",
- "10_year",
- "20_year",
- "100_year",
- "100_year_climate_change",
- "500_year",
- "1000_year"
-]New value: +[
+ "5_year",
+ "10_year",
+ "20_year",
+ "50_year",
+ "100_year",
+ "100_year_climate_change",
+ "500_year",
+ "1000_year",
+ "10000_year"
+]analyse_roof1 field changedInput schema / properties / buildingId / descriptionPrevious value: -"The baseray building id returned by find_buildings or search_buildings."New value: +"The baseray building id (`buildingId` in an earlier result)."find_buildings1 field changedInput schema / properties / address / descriptionPrevious value: -"A street address in Romania or Czechia, with the town, e.g. \"Bulevardul Eroilor 10, Brașov\"."New value: +"A street address with the town, e.g. \"Bulevardul Eroilor 10, Brașov\"."get_building1 field changedInput schema / properties / buildingId / descriptionPrevious value: -"The baseray building id returned by find_buildings or search_buildings."New value: +"The baseray building id (`buildingId` in an earlier result)."list_building_units1 field changedInput schema / properties / buildingId / descriptionPrevious value: -"The baseray building id returned by find_buildings or search_buildings."New value: +"The baseray building id (`buildingId` in an earlier result)."open_buildings1 field changedInput schema / properties / buildingIds / descriptionPrevious value: -"The baseray building ids to open, 1 to 25, from search_buildings or find_buildings."New value: +"The baseray building ids to open, 1 to 25 (`buildingId` in earlier results)."analyse_rooffind_buildingsget_buildinglist_building_unitslist_lead_listsopen_buildingssave_buildings_to_lead_listsearch_buildingssearch_placesDutch address data for AI assistants: BAG building facts, energy labels, reviewed crime signals.
Indicative commercial rooftop solar assessments for Australian buildings, from open map data.
French real estate data: cadastre, DVF sales, DPE energy ratings, price estimates, parcel context
Dutch property report by address: build year, energy label, neighbourhood, monument, schools.
Add one secure layer between your agents and this server.
