> ## Documentation Index > Fetch the complete documentation index at: https://docs.gabin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Tools > The 18 read-only tools of the Gabin MCP server: companies and officers, buildings and real estate, zones and addresses, multi-criteria search. Every tool reads one resource of the [REST API](https://docs.gabin.ai/quickstart.md) and returns it twice: as a short text, one line per object with its identifiers and `gabin_url`, for clients that only show text to the model, and as `structuredContent`, the full JSON matching the tool's published `outputSchema`. The objects are the same as in the API: a `company` here is the `data` of `GET /v1/companies/{siren}`, with the same fields and the same descriptions. All tools are annotated `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true` and `openWorldHint: false`: a client can call them without confirmation and replay them. None of them writes anything. **Pagination.** List tools take `limit` (1 to 100, default 20) and `cursor`, and return `total`, `total_kind` (`exact`, `lower_bound` or `estimate`) and `next_cursor`. To get the next page, call again with the same arguments and `cursor: next_cursor`. A query stops at 10,000 results. **Errors.** An API error comes back as a tool result with `isError: true` and a text such as `NOT_FOUND: Resource not found. Find the SIREN with search_companies.`: the API code, its message, the delay to wait when there is one, and the tool's own hint on what to do next. An argument combination the schema cannot express (for example `find_buildings` without an area) is refused before any call with `INVALID: …`. Codes are those of the API: see [Errors](https://docs.gabin.ai/errors.md). **Weights.** A call weighs one quota unit. Each extra section (`get_building`), include (`get_company`) or `include_market` (`get_zone`) is one more request, fetched in the same call. `advanced_search` weighs 5, and 5 more with `count`. See [Limits](https://docs.gabin.ai/limits.md). ## Companies and officers ### search\_companies Finds French companies (SIRENE legal units) by name, SIREN or SIRET, and/or by filters. With a location, a company matches when it has an establishment there, open or closed. With a name, exact names come first. With neither name nor location, the largest active companies by latest revenue come first. Active companies only unless `include_closed`. | Input | Description | | - | - | | `q` | Name (prefix or contained words), SIREN or SIRET. Example: `"atelier thermique"`. | | `naf` | Activities, comma-separated, up to 20: sub-classes (`"43.29A"`), divisions (`"47"`) or sections (`"G"`). | | `sector` | A Gabin sector, a named group of NAF sub-classes. Example: `plomberie-chauffage`. | | `insee`, `iris`, `department` | Location: INSEE code of a city or arrondissement, IRIS code of a district, department code. | | `headcount` | INSEE headcount range code. Example: `"11"` (10 to 19 employees). | | `legal_form` | Legal form families, comma-separated. Example: `"sas,sarl"`. | | `revenue_min`, `revenue_max` | Latest reported revenue, in euros. | | `created_after` | Companies created on or after this date (`YYYY-MM-DD`). Requires a location. | | `include_closed`, `headquarters_only` | Include ceased companies; keep the registered office only for the location match. | | `cursor`, `limit` | Pagination. | Returns `companies` (summaries: SIREN, name, NAF code and label, registered office city, headcount range, `active`, `gabin_url`), `total`, `total_kind`, `next_cursor`. `ZONE_REQUIRED` comes back when `created_after` is used without a location, or when a search without location on a rare activity would take too long: add `insee`, `iris` or `department`. **Use it** to turn a name into a SIREN, or to list the companies of an activity in a city (codes from [`lookup_reference`](#lookup_reference) and [`search_cities`](#search_cities)). Next: `get_company`. ### get\_company Full profile of a company by SIREN: identity, legal form, NAF activity, headcount, size category, share capital, VAT number, registered office (address, IRIS district, BDNB building), RNE registry facts (corporate purpose, fiscal year end), latest accounts summary and latest BODACC collective procedure. | Input | Description | | - | - | | `siren` | 9 digits. A SIRET (14 digits) is accepted: its first 9 digits are used. | | `include` | Extra sections fetched in the same call, one unit each: `officers` (people and corporate officers registered at the RNE; a person's `id` opens `get_officer`), `financials` (filed annual accounts, up to 10 fiscal years, income statement and balance sheet items in euros). | Returns `company`, plus `officers` and `financials` when requested. **Use it** for anything about one company. Establishments: `list_company_establishments`; buildings occupied or owned: `list_company_buildings`. ### list\_company\_establishments Establishments (SIRET) of a company, open and closed: registered office first, then open ones, newest first. Each has its address, INSEE city code, NAF code, dates, WGS84 position and the BDNB building it occupies when its address matches one at street-number level. | Input | Description | | - | - | | `siren` | 9 digits (or a SIRET). | | `cursor`, `limit` | Pagination. | Returns `establishments`, `total`, `total_kind`, `next_cursor`. **Use it** to locate where a company operates. Next: `get_building` with an establishment's building id. ### get\_establishment One establishment by SIRET, with the name of its company: address, NAF code, dates, position and BDNB building. | Input | Description | | - | - | | `siret` | 14 digits (SIREN + 5). Example: `55210055400013`. | Returns `establishment` (with `company_name` and `siren`). **Use it** when you start from a SIRET. The company itself: `get_company` with the first 9 digits. ### search\_officers People holding a mandate in a French company (RNE register), found by name. Exact identities first; each result names one company of the person to tell namesakes apart. Not paginated: add the first name to narrow. | Input | Description | | - | - | | `q` | Name, with the first name when known. | | `limit` | 1 to 20. | Returns `officers` (first names, last name, birth month, `id`, role and company name, `gabin_url`). **Use it** to find a person's `id`. Next: `get_officer`. ### get\_officer An officer (person) by id: mandates in every company where the same identity (name, first names, birth month) appears, each with the company summary and whether the mandate is active, and a bounded relationship graph (their companies and the other officers of those companies). Companies under partial diffusion are never linked to a person. | Input | Description | | - | - | | `id` | Officer id, from `search_officers` or `get_company` with `include: ["officers"]`. | Returns `officer`. **Use it** to list what a person runs, or to walk from a person to their co-officers. ### lookup\_reference Values accepted by the `search_companies` filters, with their official French labels. | Input | Description | | - | - | | `kind` | `naf` (NAF rev. 2 sub-classes, 732, with class, division, section and Gabin sector), `legal_forms` (legal form families) or `headcount_ranges` (INSEE ranges with their bounds). | | `q`, `section`, `code` | With `kind: "naf"`, at least one is required: words of the label or the start of a code, a section letter, or one exact code. | Returns `naf`, `legal_forms` or `headcount_ranges` depending on `kind`. **Use it** before `search_companies` when the question names an activity, a legal form or a size in words. ## Buildings and real estate ### get\_building A building (BDNB) by id: name of the place, addresses, city and IRIS district, use, construction year, levels, dwellings, footprint area and polygon, height, representative energy class (DPE), heating energy, count of linked companies. | Input | Description | | - | - | | `id` | BDNB building id. Example: `"bdnb-bg-CJ69-HW8G-PTTG"`. | | `sections` | Fetched in the same call, one unit each. | | Section | Content | | - | - | | `energy` | DPE certificates (housing and tertiary) and class distribution. | | `transactions` | DVF property sales on its parcels since 2014, median price per m². | | `owners` | Corporate owners from land files, then likely owners among the occupants (sole proprietorships included). | | `condominium` | RNIC register entry and its professional manager (syndic). | | `parcels` | Cadastral parcels with boundaries. | | `parking` | Condominium lots, OpenStreetMap parkings, EV charging stations nearby. | | `permits` | Building permits (Sitadel) on its parcels. | | `fiber` | Fiber deployment (Arcep). | | `planning` | Local urban plan zone (PLU), safeguard plan, heritage easements. | | `market` | Prices, rents, population and income of its city and district. | Returns `building`, plus one key per requested section. **Use it** once you have a building id from `geocode_address`, `search_places`, `find_buildings`, an establishment or a company's registered office. Companies in or owning the building: `get_building_companies`. ### get\_building\_companies Companies linked to a building: occupants (an establishment matched to the building's address or position) and corporate owners (land files), each with its role(s), company summary and, for an occupant, the establishment (SIRET, trade name, NAF, open or closed). Sole proprietorships appear as occupants under their registered name; never a company under partial diffusion. | Input | Description | | - | - | | `id` | BDNB building id. | | `cursor`, `limit` | Pagination. | Returns `companies`, `total`, `total_kind`, `next_cursor`. **Use it** to answer "who is in this building" and "which company owns it". ### list\_company\_buildings Buildings a company occupies (its establishments matched to a BDNB building, open or closed) and owns (land files), merged by building: building summary, roles, SIRETs located there, premises owned. Occupied and owned first. Empty for a sole proprietorship or a company under partial diffusion. | Input | Description | | - | - | | `siren` | 9 digits (or a SIRET). | | `cursor`, `limit` | Pagination. | Returns `buildings`, `total`, `total_kind`, `next_cursor`. **Use it** for the real-estate footprint of a company. Next: `get_building` for one of them. ### find\_buildings Buildings (BDNB) in one area with simple filters. | Input | Description | | - | - | | Area, one of | `bbox` (up to 2 km × 2 km), `lat` + `lon` + `radius` (up to 1,000 m), `insee` (city), `iris` (district). | | `usage` | Main uses, any of: `residential`, `tertiary`, `industrial`, `mixed`. | | `built_after`, `built_before` | Construction year bounds. | | `dpe` | Energy classes, any of `A` to `G`. Example: `["F", "G"]`. | | `min_companies` | Minimum number of linked companies, 1 to 1,000. | | `cursor`, `limit` | Pagination. | Returns `buildings` (summaries: id, address, use, year, dwellings, DPE, companies count, center, `gabin_url`), `total`, `total_kind`, `next_cursor`. Without an area the call is refused with `INVALID`. **Use it** for "buildings around this point" or "buildings of this kind in this district". For conditions on owners, occupants, certificates or condominiums, use `advanced_search`. ### get\_parcel A cadastral parcel by id: section, number, area, boundary (GeoJSON), city, district and the buildings standing on it. | Input | Description | | - | - | | `id` | Cadastral parcel id (14 characters), from `get_building` with `sections: ["parcels"]` or from transactions. | Returns `parcel`. **Use it** to go from a parcel to its buildings. Owners are not listed here: `get_building` with the `owners` section. ## Zones and addresses ### geocode\_address Geocodes a French address (Base Adresse Nationale): normalized label, city and INSEE code, precision (house number, street, locality, city), score, WGS84 position, and the BDNB building at the address point for a house-number match. | Input | Description | | - | - | | `q` | The address, with the city. | | `limit` | 1 to 10. | Returns `results`. **Use it** as the first step of any question that starts with an address. Next: `get_building` with the matched building id. For a named place, use `search_places`. ### search\_places Named places (residences, hospitals, schools, retirement homes, hotels, shops…) by name, optionally followed by the city, each with its BDNB building. | Input | Description | | - | - | | `q` | The name, then the city. | | `limit` | 1 to 10. | Returns `places` (name, category, city, `building_id`). **Use it** when the question names a place rather than an address. Next: `get_building`. ### search\_cities Cities and the arrondissements of Paris, Lyon and Marseille by name (prefix), postal code or INSEE code: INSEE code, department, main postal code, population, center. | Input | Description | | - | - | | `q` | City name prefix, postal code or INSEE code. Example: `"villeurb"`, `"69100"`. | Returns `cities`. **Use it** to get the INSEE code that `search_companies`, `find_buildings` and `advanced_search` take as a location. Next: `get_zone` for its districts or market figures. ### get\_zone A zone and what it contains. | Input | Description | | - | - | | `level` | `city` (INSEE code: the city and its named districts with IRIS codes), `district` (IRIS code: the district and its city), `department` (code: its cities, with the arrondissements of Paris, Lyon and Marseille), `region` (code: market figures only, `include_market` required). | | `code` | The code at that level. | | `include_market` | Adds the market sheet (one more unit): sale prices per m² (DVF) by segment, most active streets, rents (ANIL), population by age and occupation (census) and income (FiLoSoFi), yearly, for the zone and every level containing it. | Returns `city` and `districts`, or `district`, or `cities`, depending on `level`, plus `market` when requested. **Use it** for the figures of a territory and to find the IRIS codes of a city. ## Multi-criteria search ### list\_search\_fields Catalog of the fields `advanced_search` can filter on, for buildings (BDNB characteristics, energy certificates, condominium, owners, occupants) and companies: id, target, type, operator, unit, accepted values with French labels, meaning and source. | Input | Description | | - | - | | `target` | `buildings` or `companies`. Omit for both. | Returns `fields`. This tool does not read the database and is cheap to call. **Use it** before composing an `advanced_search`: field ids, operators and values come from here. ### advanced\_search Buildings or companies (registered offices) in a zone matching conditions on catalog fields: all `conditions` apply (AND), and at least one condition of each `any_of` group (OR). This is the advanced search of the gabin.ai map. | Input | Description | | - | - | | `target` | `buildings` (BDNB buildings) or `companies` (registered offices). | | `zone` | `{ type, code }`: a city (INSEE code), a district (IRIS code), a postal code, or a department (buildings only). Required: without it, or for companies in a whole department, the call is refused with `ZONE_REQUIRED`. | | `conditions` | Up to 12 conditions `{ field, values?, min?, max? }`: `values` for enum, NAF, boolean (`["true"]`) and text (prefix) fields, `min`/`max` inclusive for numbers. Empty: everything in the zone. | | `any_of` | Up to 4 groups of 2 to 6 conditions; at least one condition of each group applies. 12 conditions in total with `conditions`. | | `count` | Also returns the total (counted up to 100,000) and breakdowns by use, energy class, city… 5 more units. | | `cursor`, `limit` | Pagination. | Returns `results` (building rows: id, address, city, use, construction year, dwellings, DPE, `gabin_url`; company rows: SIREN, name, NAF, city, headcount range, `gabin_url`), `total`, `total_kind`, `next_cursor`, and `count` when requested. Each call weighs 5 units. An unknown field, operator or value is refused with `INVALID`. **Use it** for prospecting: "residential buildings built before 1975 with a DPE F or G and a professional manager in this city", "SAS companies in this postal code with a given activity". Next: `get_building` or `get_company` on a result. > [!TIP] > > The server's instructions give the agent the typical chains: name → `search_companies` → `get_company` → `list_company_establishments` or `list_company_buildings`; address → `geocode_address` → `get_building` → `get_building_companies`; criteria in an area → `list_search_fields` → `advanced_search`. Example prompts are in the [overview](https://docs.gabin.ai/mcp/overview.md#example-prompts). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.