French B2B database for companies and contacts, from official French registers (INSEE, Infogreffe, BODACC) and public web sources. Search, count, fetch entities and export a small CSV from Claude or any MCP client. OAuth with a Basile account; API-access plan required. France only.
Score is being calculated.
Autocomplete d'ACTIVITÉ/MÉTIER → renvoie des IDs de concept unifiés (NAF + catégories Google + industries LinkedIn).
À utiliser pour remplir le filtre activity (people ET companies). Ex. q="restaurant", q="plomberie".
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Terme métier à rechercher (ex. "boulangerie", "avocat"). | |
| limit | No | Nb de suggestions (défaut serveur). |
| Name | Required | Description |
|---|---|---|
| bounds | No | Champs *_bounds : les bornes min/max renvoyées telles quelles (results vaut alors []). |
| results | Yes | Valeurs proposées, à recopier telles quelles dans les filtres. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by explaining that the tool returns unified concept IDs from multiple taxonomies (NAF, Google, LinkedIn), which is useful for understanding the output. It doesn't mention pagination or default limit behavior, but the schema covers the limit parameter. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core function in the first sentence, then the use case, then examples. Every sentence earns its place, and there is no redundant 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?
The tool is simple (2 params, 1 required, no nested objects) and has an output schema, so the description doesn't need to explain return values. The description covers the purpose, use case, and examples. It could mention the default limit behavior or the exact structure of the returned IDs, but given the simplicity and schema coverage, it is nearly complete.
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 schema already documents both parameters (`q` and `limit`). The description adds a bit of context by showing example values for `q` and explaining the purpose of the returned IDs, but it doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: autocomplete for ACTIVITÉ/MÉTIER that returns unified concept IDs (NAF + Google categories + LinkedIn industries). It specifies the exact use case (filling the `activity` filter for both people and companies) and gives concrete examples. This distinguishes it from sibling tools like basile_suggest and basile_search_*.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it: 'À utiliser pour remplir le filtre `activity` (people ET companies).' It also provides examples of queries. However, it does not explicitly state when NOT to use it or mention alternatives (e.g., basile_suggest) for other suggestion needs, so it falls 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.
Renvoie le NOMBRE TOTAL de résultats pour des filtres. GRATUIT : aucun crédit débité, et le total est EXACT (non plafonné).
À appeler TOUJOURS en premier — les outils de recherche/export, eux, coûtent 1 crédit par fiche.
Companies : renvoie aussi establishmentsTotal = nb de POINTS DE VENTE (fiches Google) derrière les sociétés dédupliquées (ex. 420 sociétés mais 800 points de vente).
FORME DES FILTRES :
Filtre texte = {"include":[...], "exclude":[...]} — include = OR, exclude = NOT.
Plusieurs filtres différents = ET entre eux.
People : filtres numériques = range objet {">=":n,"<=":n} (ops >, >=, <, <=).
Companies : filtres numériques = champs simples _min / _max (ex. capital_min, headcount_max).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | people = personnes/contacts ; companies = entreprises | |
| filters | Yes | Objet de filtres Basile (clés détaillées dans basile_search_people / basile_search_companies). |
| Name | Required | Description |
|---|---|---|
| note | No | Avertissement éventuel sur la fiabilité du total. |
| total | Yes | Nombre total de résultats — exact, jamais plafonné. |
| establishmentsTotal | No | Companies : nb de points de vente (fiches Google) derrière les sociétés dédupliquées. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond these: no credit is debited, the total is exact and not capped, and Companies returns an additional `establishmentsTotal` for points of sale. This gives the agent a fuller model of side effects and outputs.
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 dense but well-structured, with a front-loaded summary of behavior, a special note for Companies, and bullet-like filter syntax rules. Every sentence earns its place by conveying critical usage or cost information without redundancy.
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?
The description is complete for a counting tool: it covers purpose, cost, output semantics, filter structure, kind-specific differences, and points to sibling descriptions for the full key list. The presence of an output schema means return values need not be repeated here. An agent has enough to call this tool correctly in context.
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?
Although the schema covers both parameters, the schema's description of `filters` is generic, pointing to sibling tools. The tool description compensates by explaining concrete filter syntax: include/exclude objects with OR/NOT semantics, AND between different filters, numeric range objects for People, and `_min`/`_max` fields for Companies. This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise purpose: 'Renvoie le NOMBRE TOTAL de résultats pour des filtres.' It clearly distinguishes this tool from search/export siblings by emphasizing that it returns only a count, is free, and is exact. The title 'Compter sans extraire' reinforces the differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use it: 'À appeler TOUJOURS en premier.' It contrasts with search/export tools by noting they cost 1 credit per record, making the alternative usage condition clear. It also references basile_search_people / basile_search_companies for detailed filter keys, further guiding tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exporte un CSV COMPLET (~70-79 colonnes) pour des filtres OU une liste d'ids. CONSOMME le quota d'export du plan.
Companies : mode = "companies" (1 ligne / entreprise, défaut) OU "locations" (1 ligne par POINT DE VENTE / établissement Google — à utiliser quand establishmentsTotal > total).
⚠️ Compte d'abord (basile_count). Deux chemins, choisis AUTOMATIQUEMENT selon le volume :
≤ 500 lignes → le CSV est renvoyé INLINE dans la conversation ;
500 lignes → un export FICHIER est lancé côté serveur et tu reçois un jobId, puis un LIEN de téléchargement via basile_export_status. Plafond = celui du plan (20 000 lignes/export en plan API, 50 000 en Agence), pas celui du chat. maxRows = plafond/export du plan ; capped = il reste des résultats au-delà.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Liste d'_id précis à exporter (alternative aux filtres). | |
| kind | Yes | people = personnes/contacts ; companies = entreprises. | |
| mode | No | Companies uniquement : "companies" (entreprises, défaut) ou "locations" (points de vente / établissements Google). | |
| filters | No | Filtres (ou utilise `ids`). |
| Name | Required | Description |
|---|---|---|
| csv | No | mode=inline : le CSV complet, en-tête inclus. |
| mode | Yes | inline = CSV dans `csv` ; file = fichier en construction/prêt (`jobId`) ; empty = aucun résultat ; oversized = trop gros pour l'inline, quota déjà débité. |
| jobId | No | mode=file : identifiant à repasser à basile_export_status. |
| ready | No | mode=file : true quand le fichier est téléchargeable. |
| status | No | mode=file : queued | running | done | partial | failed. |
| message | Yes | Résumé en clair, destiné à être lu tel quel. |
| filename | No | Nom du fichier produit. |
| rowCount | No | Nb de lignes de données (hors en-tête). |
| expiresAt | No | Date d'expiration du fichier (ISO 8601). |
| truncated | No | Fichier coupé au plafond par export du plan. |
| downloadUrl | No | Lien de téléchargement direct, valable ~1 h. |
| planMaxRows | No | Plafond de lignes par export du plan, tel que renvoyé par l'API. |
| quotaReached | No | Quota mensuel d'export atteint pendant la construction. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial context beyond this: 'CONSOMME le quota d'export du plan' reveals a quota side effect, the dual execution paths (inline vs server-side file with jobId) disclose async behavior, plan caps (20 000/50 000 lignes) are quantified, and maxRows/capped semantics explain result truncation. No contradiction with annotations — consuming quota is consistent with non-read-only, non-destructive.
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?
Every sentence earns its place: purpose, quota warning, mode rule, count-first prerequisite, execution paths, plan limits, and result semantics. The information is front-loaded (purpose and quota warning first), and the two-path workflow is presented with clear thresholds. Though dense, the length is justified by the tool's operational complexity — this is efficiency, not bloat.
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 4-param tool with nested filters, an output schema, async file export, and quota constraints, the description covers the critical operational surface: prerequisite (count first), automatic path selection with exact thresholds, follow-up status tool, plan caps, and response flags (maxRows, capped). The only minor gap is a concrete example of the open-ended filters object, but the 100% schema coverage and existing output schema mitigate this.
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. The description adds a meaningful decision rule for `mode` — '1 ligne / entreprise, défaut' vs '1 ligne par POINT DE VENTE / établissement Google — à utiliser quand establishmentsTotal > total' — which goes beyond the schema's enum listing. It also reinforces the ids-vs-filters alternative. A concrete filters example would push this to 5, but the schema already documents all parameters well.
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 opens with a specific verb+resource+scope: 'Exporte un CSV COMPLET (~70-79 colonnes) pour des filtres OU une liste d'ids.' It clearly distinguishes the tool from its siblings: basile_count counts, basile_export_status checks status, basile_search_* and basile_suggest search/suggest, while this is the only exporter. An agent can identify its role immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit operational guidance: 'Compte d'abord (basile_count)' establishes the prerequisite, 'via basile_export_status' names the follow-up tool, and 'à utiliser quand establishmentsTotal > total' gives a concrete selection rule for the locations mode. The two execution paths (inline ≤500 lines vs file >500 lines) are spelled out with exact thresholds, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suit un export FICHIER lancé par basile_export (au-delà de 500 lignes) et renvoie, dès qu'il est prêt, un LIEN de téléchargement direct valable ~1 h. Attend jusqu'à ~40 s : si l'export n'est pas fini, rappelle le même jobId (la construction continue côté serveur). Ne consomme aucun quota : le débit a eu lieu au lancement.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Identifiant renvoyé par basile_export (champ jobId). |
| Name | Required | Description |
|---|---|---|
| jobId | Yes | L'identifiant suivi. |
| ready | Yes | true quand le fichier est téléchargeable. |
| status | Yes | queued | running | done | partial | failed. |
| message | Yes | Résumé en clair, destiné à être lu tel quel. |
| filename | Yes | Nom du fichier produit. |
| rowCount | Yes | Lignes écrites à cet instant. |
| expiresAt | Yes | Expiration du fichier (ISO 8601). |
| truncated | Yes | Fichier coupé au plafond par export du plan. |
| downloadUrl | Yes | Lien de téléchargement direct, valable ~1 h ; null tant que ce n'est pas prêt. |
| quotaReached | Yes | Quota mensuel d'export atteint pendant la construction. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses polling behavior (wait ~40s, reuse the same jobId), link validity, and quota impact ('ne consomme aucun quota'). This adds meaningful behavioral detail beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the core purpose placed first and behavior details following. No filler or repeated schema 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?
Covers the essential operational details: source tool, threshold, wait time, retry semantics, output type, and quota impact. With an output schema present, nothing critical 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?
The schema already documents jobId, and the description reinforces its origin (from basile_export) and its reuse across polls. This goes beyond the bare schema definition.
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 action (follow/poll an export launched by basile_export) and a clear result (returns a direct download link). It also distinguishes its scope ('FICHIER' and 'au-delà de 500 lignes') from the general export flow.
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 ties usage to a prior basile_export call and defines the relevant condition (file exports over 500 rows). It lacks a formal 'when not to use' or alternative comparison, but the intended context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Récupère la fiche d'une personne ou entreprise par son _id (issu d'un search). full=true → toutes les colonnes enrichies (même schéma que l'export CSV). ⚠️ COÛT : 1 crédit par appel, y compris si la fiche a déjà été payée dans un search précédent (il n'y a pas de registre « déjà payé »). Ne pas boucler dessus sur une liste de résultats : pour plusieurs fiches, basile_export coûte pareil et renvoie tout d'un coup.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Le _id du résultat (renvoyé par basile_search_*). | |
| full | No | true = fiche complète /full (défaut true). | |
| kind | Yes | people = une personne/contact ; companies = une entreprise. |
| Name | Required | Description |
|---|---|---|
| entity | Yes | La fiche, telle que renvoyée par l'API Basile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds useful behavioral context beyond the annotations: a clear cost warning (1 credit per call, no 'already paid' registry), which is important for agent planning, and it specifies that full=true returns the same enriched columns as the CSV export. This is meaningful and non-redundant.
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 compact and front-loaded: the first sentence states the core purpose, the second clarifies full mode, and the third gives the cost/routing caveat. There is no filler; every sentence conveys a decision-relevant fact. The warning about basile_export is the most important guidance for avoiding misuses and is included concisely.
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 the output schema exists and the annotations already define safety/interactivity, the description is complete as far as the data needs to be. It adequately specifies the expected input provenance (from search), explains full mode, and hands off bulk work to basile_export. No crucial gap remains for an agent to call this 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 the schema already documents id, kind, and full with descriptions. The tool description adds the 'full=true → all enriched columns' meaning, but that is largely supported by the schema's own parameter description. It does not provide significant extra parameter semantics beyond what the schema already gives, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves a detailed record for a person or company via its _id, with an explicit definition of what full=true means. It also differentiates the tool from sibling tools by noting the cost and the availability of basile_export for bulk retrieval, so an agent can distinguish this lookup tool from the search and export 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?
The description is explicit about when to use this tool: after a search, for a single entity. It also gives a concrete when-not-to-use rule, warning against looping over many ids and directing the agent to basile_export for multiple records. This directly addresses alternative selection, without leaving it to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cherche des ENTREPRISES (registre légal + LinkedIn + Google My Business) dans Basile.
Renvoie { total, establishmentsTotal, leads[], pagination.nextToken }. limit défaut 25, max 1000.
total = sociétés (dédupliquées par domaine) ; establishmentsTotal = POINTS DE VENTE (fiches Google). Pour exporter les points de vente : basile_export avec mode:"locations".
⚠️ COÛT : 1 crédit par fiche renvoyée (limit=25 → 25 crédits), à chaque appel. Compte d'abord avec basile_count (gratuit et exact) ; le total renvoyé ici est plafonné à 100 000.
FORME DES FILTRES :
Filtre texte = {"include":[...], "exclude":[...]} — include = OR, exclude = NOT.
Plusieurs filtres différents = ET entre eux.
People : filtres numériques = range objet {">=":n,"<=":n} (ops >, >=, <, <=).
Companies : filtres numériques = champs simples _min / _max (ex. capital_min, headcount_max).
FILTRES COMPANIES (POST /companies/find) : Généraux (3 sources Legal+LKI+GMB) : name (contains), activity (métier unifié — le plus puissant ; IDs via basile_activity_suggest), with_email (bool, uniquement les entreprises dont le domaine a au moins un email crawlé). Legal-only : naf_code (préfixe ".x" possible, ex "41.x"), headquarters_naf_code, headquarters_department_code (ex "75","13"), headquarters_postal_code, legal_form (accepte code court SARL/SAS/SASU/EURL/SA/SCI…, code INSEE 5710, OU libellé complet), legal_category (code INSEE), siren, capital_min/capital_max, publishable (bool), creation_date_min/creation_date_max (année ex "2015"), created_since_months (nombre — entreprises créées dans les N derniers mois, ex 3 ; plus précis que creation_date pour « créées récemment »). Région : utiliser region (NOM canonique, ex "Île-de-France") ou headquarters_department_code (ex "75"). ⚠️ headquarters_region_code (code INSEE) est IGNORÉ (no-op, pas de résolveur) — ne pas l'utiliser. Legal+LKI (exclut GMB) : headquarters_city, headquarters_country_code (ex "FR"), headcount_min/headcount_max (effectif). LinkedIn-only : domain (contains), tech_stack (techno du site, ex "Shopify"/"WordPress"). ⚠️ followers : pas de données → ne pas utiliser. ⚠️ industry_main / company_type = LinkedIn, lacunaires/peu fiables → pour un secteur préférer activity ou naf_code. GMB-only : rating_min/rating_max (0-5), reviews_min/reviews_max, is_opening (bool, ouvert dimanche). Spécial : company_ceased (bool) — METTRE false par défaut (entreprises actives uniquement). Pilotage source : source ("Legal"|"LKI"|"GMB"), with_legal_data (bool), with_linkedin_page (bool). CONSEILS : métier → activity (IDs via basile_activity_suggest) sinon naf_code. France → headquarters_country_code:{include:["FR"]} ou headquarters_department_code.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Nb de résultats à renvoyer (défaut 25). | |
| filters | Yes | Filtres companies (voir description). | |
| paginationToken | No | Curseur `pagination.nextToken` de la page précédente. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Nb de fiches réellement renvoyées dans cette page (= crédits débités). |
| leads | Yes | Les entreprises de cette page. |
| total | Yes | Sociétés dédupliquées, total PLAFONNÉ à 100 000 — pour l'exact, basile_count. |
| nextToken | Yes | Curseur de la page suivante ; null quand il n'y en a plus. |
| establishmentsTotal | Yes | Points de vente (fiches Google) derrière ces sociétés ; null si Google ne participe pas. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey read-only and idempotent behavior, so the description earns credit for going beyond them. It discloses the 1-credit-per-record cost, the 100,000 cap on `total`, the `kredentials` no-op behavior of headquarters_region_code, and the semantic difference between companies and points de vente. This is strong operational context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it is well-structued with headers, source categories, and front-loaded critical information such as output shape, cost, and pagination. Every large block maps to a real filter/selection decision, though the density of the filter list makes it require careful reading.
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 complex, filter-heavy tool with a rich output schema, the description provides everything needed to call it correctly: return semantics, limit behavior, pagination token, cost, source coverage, no-op fields, and recommended tools. I see no decision-relevant gap that the agent would be forced to guess about.
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?
The input schema treats `filters` as an opaque object with no structured properties, so the description carries nearly all the filter semantics. It defines the include/exclude shape, AND/OR behavior, numeric operator formats, legal-related fields, source-specific fields, special flags like company_ceased, and avoided fields. This is far beyond the minimal schema descriptions.
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 explicitly states that the tool searches companies (ENTREPRISES) across Legal, LinkedIn, and Google My Business, names the exact return shape (`total`, `establishmentsTotal`, `leads[]`, `pagination`), and distinguishes itself from nearby tools like basile_search_people, basile_export, and basile_count. An agent can identify when to use this tool without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage guidance: use basile_count first for an exact free count, use basile_export with mode:'locations' to export points de vente, and prefer activity or naf_code over unreliable LinkedIn fields. It also warns about unused/no-op fields, so when-not-to-use guidance is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cherche des PERSONNES/contacts (dirigeants légaux + profils LinkedIn) dans Basile.
Renvoie { total, leads[], pagination.nextToken }. Utilise nextToken pour paginer.
limit défaut 25, max 1000. La page > 1 nécessite un abonnement actif (402 sinon).
⚠️ COÛT : 1 crédit par fiche renvoyée (donc limit=25 → 25 crédits), à chaque appel, sans déduplication d'un appel à l'autre. Compte d'abord avec basile_count (gratuit), et ne demande que le nombre de fiches réellement utile. Le total renvoyé ici est plafonné à 100 000 : pour un volume exact, utiliser basile_count.
FORME DES FILTRES :
Filtre texte = {"include":[...], "exclude":[...]} — include = OR, exclude = NOT.
Plusieurs filtres différents = ET entre eux.
People : filtres numériques = range objet {">=":n,"<=":n} (ops >, >=, <, <=).
Companies : filtres numériques = champs simples _min / _max (ex. capital_min, headcount_max).
FILTRES PEOPLE (POST /people/find) : Communs (2 sources Legal + LKI) : activity (secteur/métier de l'entreprise de la personne — IDs concept via basile_activity_suggest, ou préfixes naf:/lki:/gmb:), result_full_name, result_last_name, result_first_name, result_role (intitulé de poste, TEXTE → mettre toutes les variantes ; ex. CEO+PDG+Directeur Général…), result_city, region (RÉGION française canonique, ex "Île-de-France" — couvre Legal+LKI), result_country, result_country_code (ex. "FR"), employer. Legal-only (activer = exclut LinkedIn) : mandate_role (gerant|president|dg|dgd|administrateur|commissaire_comptes|associe|directeur_non_dg|autre), result_used_first_name, result_postal_code, siren, legal_name, nationality, nationality_code, result_is_legal_entity (bool), result_is_current (bool, mandat actuel), result_age (range), result_total_companies_count (range). LinkedIn-only (activer = exclut Legal) : current_seniority (C-Level|Director|VP|Head|Manager|Senior|Partner|Owner|Founder|Entry|Training|Unpaid), current_job_functions, skills, languages, education, past_title, past_employer, tenure_bucket, past_tenure_bucket, current_tenure_years (range, ancienneté au poste ACTUEL en années — plus fin que tenure_bucket), connection_count (range), linkedin_url (retrouver un profil par son URL/handle LinkedIn — à coupler avec source:"LKI"). Taille de l'employeur (MULTI-SOURCE, n'exclut aucune source) : company_headcount (range) — effectif de la société ACTUELLE du contact, croisant l'effectif exact du registre légal et la bande de taille déclarée sur LinkedIn. C'est LE filtre pour « dirigeants de PME de 50 à 200 personnes » ; ne pas le confondre avec un filtre sur les entreprises. Les fiches sans effectif connu sont exclues (~21 % sur un échantillon FR). Pilotage source : source ("Legal"|"LKI"), with_legal_data (bool), with_linkedin_profile (bool), hide_legal_entities (bool, RECOMMANDÉ par défaut pour ne lister que de vraies personnes). CONSEILS : secteur → activity direct, taille d'entreprise → company_headcount direct. NE JAMAIS enchaîner une recherche entreprises puis une recherche personnes pour filtrer par secteur ou par taille : ces deux filtres font le travail en UNE requête. Le workflow entreprises→personnes est un fallback, réservé au cas où l'on part d'entreprises nommées ou de fiches Google. France → result_country_code:{include:["FR"]}. Dirigeants actifs → result_is_current:true. NB : le total people = somme LKI+Legal (peut sur-compter une personne présente dans les 2 sources) → meta.totalBySource + totalEstimated l'indiquent ; compter avant d'extraire.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Nb de résultats à renvoyer (défaut 25). | |
| filters | Yes | Filtres people (voir description). | |
| paginationToken | No | Curseur `pagination.nextToken` de la page précédente. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Nb de fiches réellement renvoyées dans cette page (= crédits débités). |
| leads | Yes | Les personnes de cette page. |
| total | Yes | Total, PLAFONNÉ à 100 000 — pour l'exact, utiliser basile_count. |
| nextToken | Yes | Curseur de la page suivante ; null quand il n'y en a plus. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description goes far beyond by disclosing the 1-credit-per-record cost, the 402 error for page > 1 without a subscription, the total capped at 100,000, the ~21% exclusion of records without headcount, and the over-counting when a person exists in both LKI and Legal sources. This is rich behavioral context that annotations alone cannot provide, and there is no contradiction.
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 long (~1000 words), but it is well-structured with clear sections (FORME DES FILTRES, FILTRES PEOPLE, Legal-only, LinkedIn-only, Taille de l'employeur, Pilotage source, CONSEILS), and the most critical operational facts (cost, pagination, subscription) are front-loaded before the filter catalog. The length is justified by the tool's complexity and the generic schema. A slight deduction because the CONSEILS section partially restates guidance already implied earlier.
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 tool with high complexity (many filters, two data sources, cost model, pagination, output schema), the description is essentially complete: return format, pagination cursor semantics, cost per call, subscription gating, total capping, filter syntax, all field names, source control, and actionable tips. Nothing an agent needs to call it correctly is missing, and the output schema covers the response shape.
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?
Although schema description coverage is 100%, the filters property in the schema merely says 'Filtres people (voir description)' — a pointer. The description carries the full burden: the include/exclude format, OR/NOT semantics, AND between filters, the range object form for people numeric filters vs _min/_max for company filters, and the complete list of Legal-only and LinkedIn-only fields. This adds substantial meaning far beyond the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Cherche des PERSONNES/contacts'), the exact resource (dirigeants légaux + profils LinkedIn), and the return shape ({ total, leads[], pagination.nextToken }). It explicitly differentiates from the sibling basile_search_companies and names basile_count as the counting alternative. An agent can immediately tell what this tool does and what it does not do.
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?
Extremely explicit usage guidance: use basile_count first (free) before extracting, use nextToken for pagination, page > 1 requires an active subscription, and the cost implication of limit. It also states when NOT to use a particular workflow ('NE JAMAIS enchaîner une recherche entreprises puis une recherche personnes'), naming basile_activity_suggest and basile_search_companies as alternatives. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Autocomplete pour trouver les valeurs valides avant de filtrer. Champs people : people_cities, people_companies (employeurs), people_roles, people_skills, people_languages, people_education, people_names, people_nationalities, people_seniorities, people_tenure_buckets, people_age_bounds, people_mandate_count_bounds. Champs companies : company_name, company_city, company_legal_form, company_siren. (Pour l'activité/métier, utilise plutôt basile_activity_suggest.)
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Terme recherché (non requis pour les *_bounds / *_seniorities / *_tenure_buckets). | |
| field | Yes | Le champ à autocompléter. | |
| limit | No | Nb de suggestions à renvoyer (défaut serveur, max 50). |
| Name | Required | Description |
|---|---|---|
| bounds | No | Champs *_bounds : les bornes min/max renvoyées telles quelles (results vaut alors []). |
| results | Yes | Valeurs proposées, à recopier telles quelles dans les filtres. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, which align well with an autocomplete lookup. The description adds the key behavioral idea that this is a pre-filtering suggestion tool and enumerates supported scopes, though it does not discuss rate limits or response behavior (mitigated by the presence of an output 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?
The description is front-loaded with a clear action and purpose, followed by a necessary enumeration of supported fields. The list is long but directly actionable; no filler or redundancy.
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 the input schema defining the field enum and q behavior, plus annotations establishing read-only/idempotent behavior, the description gives enough context for correct use. The only minor gap is not describing response shape or pagination, but an output schema is present.
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?
The input schema already covers all parameters with 100% coverage)Skip the baseline, so the description is not required to repeat them. It adds value by grouping fields into people vs company categoriesuring semantic labels (e.g., employeurs) and explicitly routing activité/métier queries to basile_activity_suggest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Autocomplete pour trouver les valeurs valides avant de filtrer') and enumerates the exact valid fields for people and companies. It also explicitly separates this tool from basile_activity_suggest, so an agent can immediately distinguish its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context: use this before filtering to get valid values. It also tells the agent when not to use it, pointing activité/métier queries to basile_activity_suggest.
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.
basile_activity_suggestbasile_countbasile_exportbasile_export_statusbasile_get_entitybasile_search_companiesbasile_search_peoplebasile_suggest