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.
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.
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 unlessinclude_closed.
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 and 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.
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.
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.
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.
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.
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 thesearch_companies filters, with their official French labels.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 fieldsadvanced_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.
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: allconditions apply (AND), and at least one condition of each any_of group (OR). This is the advanced search of the gabin.ai map.
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.