datafair.cloud

{
  "name": "list_datasets",
  "kind": "answer",
  "impl": "imperative",
  "description": "List datasets accessible to the current user with optional text search. Returns id, title, status, row count, and last update.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "French keywords for full-text search (simple terms, not sentences). If 0 results, try synonyms or broader terms. Examples: \"élus\", \"DPE\", \"entreprises\", \"logement social\""
      },
      "page": {
        "type": "number",
        "description": "Page number (default 1)"
      },
      "size": {
        "type": "number",
        "description": "Page size (default 10, max 50)"
      }
    }
  },
  "page": "/"
}

{
  "name": "describe_dataset",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get detailed metadata and column schema for a dataset. Returns title, description, status, owner, visibility, topics, and full column schema with types.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "datasetId": {
        "type": "string",
        "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
      }
    },
    "required": [
      "datasetId"
    ]
  },
  "page": "/"
}

{
  "name": "get_dataset_schema",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get column schema and 3 sample rows for a dataset. Call this when you do not already know the column keys and types — if they were provided to you (e.g. by the parent assistant), skip it and query directly. A rejected filter/sort/metric returns a 400 listing the column's valid operations, so you can self-correct without fetching the schema upfront.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "datasetId": {
        "type": "string",
        "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
      }
    },
    "required": [
      "datasetId"
    ]
  },
  "page": "/"
}

{
  "name": "search_data",
  "kind": "answer",
  "impl": "imperative",
  "description": "Search for data rows in a dataset using full-text search or column filters. Returns matching rows as CSV. Do NOT use for statistics — use calculate_metric or aggregate_data instead.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "datasetId": {
        "type": "string",
        "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
      },
      "q": {
        "type": "string",
        "description": "French keywords for full-text search across all dataset columns (simple keywords, not sentences). Can be combined with filters, but prefer filters alone when criteria target specific columns. Use query for broad keyword matching across all columns. Examples: \"Jean Dupont\", \"Paris\", \"2025\""
      },
      "filters": {
        "type": "object",
        "description": "Column filters as key-value pairs: column_key + suffix, all values strings. Example: { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes include _eq, _in, _gt/_lt, _search and more; if one is rejected the 400 error lists what the column supports. Never _c_-prefix a column filter (use ville_eq, not _c_ville_eq).",
        "properties": {}
      },
      "bbox": {
        "type": "string",
        "description": "Bounding box \"lonMin,latMin,lonMax,latMax\" (lon before lat), e.g. \"-2.5,43,3,47\". Geolocalized datasets only."
      },
      "geoDistance": {
        "type": "string",
        "description": "Proximity filter \"lon,lat,distance\" (lon first), e.g. \"2.35,48.85,10km\"; distance \"0\" = point-in-polygon. Geolocalized datasets only."
      },
      "dateMatch": {
        "type": "string",
        "description": "Date \"YYYY-MM-DD\" (single day) or \"YYYY-MM-DD,YYYY-MM-DD\" (range), e.g. \"2023-11-21\". Temporal datasets only."
      },
      "select": {
        "type": "string",
        "description": "Optional comma-separated list of column keys to include in the results. Useful when the dataset has many columns to reduce output size. If not provided, all columns are returned. Use column keys from describe_dataset. Format: column1,column2,column3 (No spaces after commas). Example: \"nom,age,ville\""
      },
      "sort": {
        "type": "string",
        "description": "Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random), _geo_distance:lon:lat (distance from point, for geolocalized datasets — longitude first, then latitude). Examples: \"population\" (ascending), \"-population\" (descending), \"_geo_distance:2.35:48.85\" (closest to lon=2.35, lat=48.85)"
      },
      "size": {
        "type": "number",
        "description": "Number of rows to return per page (default: 10, max: 50). Increase when you know you need more results upfront to avoid multiple pagination round-trips."
      },
      "page": {
        "type": "number",
        "description": "Page number (default 1)"
      },
      "next": {
        "type": "string",
        "description": "URL from a previous search_data response to fetch the next page of results. When provided, all other parameters (query, filters, select, sort, size) are ignored since the URL already contains them."
      }
    },
    "required": [
      "datasetId"
    ]
  },
  "page": "/"
}

{
  "name": "aggregate_data",
  "kind": "act",
  "impl": "imperative",
  "description": "Aggregate dataset rows by 1-3 columns with optional metric (sum, avg, min, max, count). Defaults to counting rows per group. For a single global metric without grouping, use calculate_metric.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "datasetId": {
        "type": "string",
        "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
      },
      "groupByColumns": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Columns to GROUP BY (like SQL GROUP BY). These define the categories/buckets, NOT the column to compute metrics on. Use column keys from describe_dataset (min 1, max 3)."
      },
      "metric": {
        "type": "object",
        "properties": {
          "column": {
            "type": "string",
            "description": "The column to compute the metric ON (e.g., \"salary\" for average salary). This is NOT the grouping column. Use column keys from describe_dataset."
          },
          "type": {
            "type": "string",
            "description": "Metric to compute on each group. \"count\" counts rows per group (identical to omitting the metric parameter — does NOT count non-null values of the specified column)."
          }
        },
        "description": "Optional metric to compute ON EACH GROUP. If not provided, defaults to counting rows per group."
      },
      "filters": {
        "type": "object",
        "description": "Column filters as key-value pairs: column_key + suffix, all values strings. Example: { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes include _eq, _in, _gt/_lt, _search and more; if one is rejected the 400 error lists what the column supports. Never _c_-prefix a column filter (use ville_eq, not _c_ville_eq).",
        "properties": {}
      },
      "bbox": {
        "type": "string",
        "description": "Bounding box \"lonMin,latMin,lonMax,latMax\" (lon before lat), e.g. \"-2.5,43,3,47\". Geolocalized datasets only."
      },
      "geoDistance": {
        "type": "string",
        "description": "Proximity filter \"lon,lat,distance\" (lon first), e.g. \"2.35,48.85,10km\"; distance \"0\" = point-in-polygon. Geolocalized datasets only."
      },
      "dateMatch": {
        "type": "string",
        "description": "Date \"YYYY-MM-DD\" (single day) or \"YYYY-MM-DD,YYYY-MM-DD\" (range), e.g. \"2023-11-21\". Temporal datasets only."
      },
      "sort": {
        "type": "string",
        "description": "Sort order for aggregation results. Use special keys: \"count\" or \"-count\" (by row count asc/desc), \"key\" or \"-key\" (by column value asc/desc), \"metric\" or \"-metric\" (by metric value asc/desc). Default: sorts by metric desc (if metric specified), then count desc. Example: \"-count\" to sort by most frequent values first"
      }
    },
    "required": [
      "datasetId",
      "groupByColumns"
    ]
  },
  "page": "/"
}

{
  "name": "calculate_metric",
  "kind": "act",
  "impl": "imperative",
  "description": "Calculate a single metric on a dataset column: avg, sum, min, max, stats, value_count, cardinality, percentiles. For per-group breakdowns, use aggregate_data.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "datasetId": {
        "type": "string",
        "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
      },
      "fieldKey": {
        "type": "string",
        "description": "The column key to calculate the metric on (use keys from describe_dataset)"
      },
      "metric": {
        "type": "string",
        "description": "Metric to calculate. Available: avg, sum, min, max (for numbers); min, max, cardinality, value_count (for strings); value_count (for others); stats returns count/min/max/avg/sum; percentiles returns distribution."
      },
      "percents": {
        "type": "string",
        "description": "Comma-separated percentages for percentiles metric (default: \"1,5,25,50,75,95,99\"). Only used when metric is \"percentiles\"."
      },
      "filters": {
        "type": "object",
        "description": "Column filters as key-value pairs: column_key + suffix, all values strings. Example: { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes include _eq, _in, _gt/_lt, _search and more; if one is rejected the 400 error lists what the column supports. Never _c_-prefix a column filter (use ville_eq, not _c_ville_eq).",
        "properties": {}
      },
      "bbox": {
        "type": "string",
        "description": "Bounding box \"lonMin,latMin,lonMax,latMax\" (lon before lat), e.g. \"-2.5,43,3,47\". Geolocalized datasets only."
      },
      "geoDistance": {
        "type": "string",
        "description": "Proximity filter \"lon,lat,distance\" (lon first), e.g. \"2.35,48.85,10km\"; distance \"0\" = point-in-polygon. Geolocalized datasets only."
      },
      "dateMatch": {
        "type": "string",
        "description": "Date \"YYYY-MM-DD\" (single day) or \"YYYY-MM-DD,YYYY-MM-DD\" (range), e.g. \"2023-11-21\". Temporal datasets only."
      }
    },
    "required": [
      "datasetId",
      "fieldKey",
      "metric"
    ]
  },
  "page": "/"
}

{
  "name": "get_field_values",
  "kind": "answer",
  "impl": "imperative",
  "description": "List distinct values of a column. Useful to discover values before filtering with _eq or _in.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "datasetId": {
        "type": "string",
        "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
      },
      "fieldKey": {
        "type": "string",
        "description": "The column key to get values for (use keys from describe_dataset)"
      },
      "q": {
        "type": "string",
        "description": "Optional text to filter values (prefix/substring match within this column)"
      },
      "sort": {
        "type": "string",
        "description": "Sort order for the values (default: asc)"
      },
      "size": {
        "type": "number",
        "description": "Number of values to return (default: 10, max: 1000)"
      }
    },
    "required": [
      "datasetId",
      "fieldKey"
    ]
  },
  "page": "/"
}

{
  "name": "subagent_dataset_data",
  "kind": "act",
  "impl": "imperative",
  "description": "Query dataset rows, compute aggregations, and explore field values. Describe the data you want in plain language — do not write filter or URL syntax yourself: the sub-agent queries and returns a ready-to-paste filterQuery for a table/map link. Provide the dataset ID; if you already know the columns (keys and types), pass them too so it can query directly without re-fetching the schema.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "The task to delegate to this sub-agent. Include all relevant context from the conversation that the sub-agent needs to accomplish the task (user preferences, constraints, data references, etc.)."
      }
    },
    "required": [
      "task"
    ]
  },
  "page": "/"
}

{
  "name": "get_current_location",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get the current page location in the portal, including its full URL, route path, name, parameters, query, and breadcrumbs.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/"
}

{
  "name": "list_pages",
  "kind": "answer",
  "impl": "imperative",
  "description": "List all available pages in the portal navigation menu, plus detail page patterns for datasets, applications, events, news, and reuses. Returns full absolute URLs — use them verbatim when writing links; substitute {slug} and append `?<query>` for filtered views, but never alter the origin or path prefix.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/"
}

{
  "name": "navigate",
  "kind": "act",
  "impl": "imperative",
  "description": "Navigate to a page in the portal. Accepts either a full absolute URL (as returned by list_pages or get_current_location) or a bare path — both work. Use list_datasets, list_applications, list_events, list_news, or list_reuses to find resource slugs/refs — prefer the human-readable `slug` over the `id` when building dataset and application paths. Optionally pass query parameters. IMPORTANT: when you search or filter data from a dataset, offer to navigate the user to the filtered table view at /datasets/{slug}/table by passing the same filter parameters as query params — but only when the search returned results (totalResults > 0).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "The destination, either a full absolute URL (e.g. as returned by list_pages) or a path (e.g. \"/datasets\", \"/datasets/my-dataset\", \"/event/my-event\"). Both are accepted."
      },
      "query": {
        "type": "string",
        "description": "Optional query string to append to the URL (without leading \"?\"). For dataset table/map pages, pass the filterQuery from the dataset_data subagent Context verbatim — do not build or edit the filter parameters yourself. On the table page you may additionally append `cols=<column keys>` to choose which columns are displayed, but do not otherwise alter the filter syntax."
      }
    },
    "required": [
      "path"
    ]
  },
  "page": "/"
}

{
  "name": "pageFilters_get",
  "kind": "answer",
  "impl": "imperative",
  "description": "Read the current page filters synced with embedded visualizations and dataset previews. Returns concept filters (keys starting with \"_c\") and per-dataset filters (keys starting with \"_d_<datasetId>_\"), plus selection markers (keys starting with \"_s_\") that tell which visualization emitted a filter. Call a block's describe_filters_* tool first to learn which keys it accepts.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/"
}

{
  "name": "pageFilters_set",
  "kind": "act",
  "impl": "imperative",
  "description": "Set or clear page filters synced with embedded visualizations and dataset previews. Pass a \"params\" object mapping filter keys to values; an empty string, null, or undefined value clears that key. Use keys advertised by a block's describe_filters_* tool (concept keys start with \"_c\", per-dataset keys with \"_d_<datasetId>_\"). When clearing a filter, also clear its selection marker (\"_s_\" + the filter key without its \"_c_\"/\"_d_\" prefix and operator suffix).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "params": {
        "type": "object",
        "description": "Map of filter key -> value. Empty/null value clears the key.",
        "additionalProperties": {
          "type": "string"
        }
      }
    },
    "required": [
      "params"
    ]
  },
  "page": "/"
}

{
  "name": "geocode_address",
  "kind": "act",
  "impl": "imperative",
  "description": "Convert a French address or place name into geographic coordinates using the IGN Geoplateforme geocoding service. Returns matching locations with coordinates, postal code, city, and relevance score.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Address or place name to search for in France. Examples: \"20 avenue de Segur, Paris\", \"Mairie de Bordeaux\", \"33000\""
      },
      "limit": {
        "type": "number",
        "description": "Maximum number of results to return (default: 5)"
      }
    },
    "required": [
      "q"
    ]
  },
  "page": "/"
}

{
  "name": "get_user_geolocation",
  "kind": "answer",
  "impl": "imperative",
  "description": "Get the current geographic position of the user using the browser Geolocation API. Returns longitude, latitude, and accuracy (for geo_distance/bbox filters use lon,lat order). The user may be prompted to grant location permission.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/"
}

{
  "name": "list_applications",
  "kind": "answer",
  "impl": "imperative",
  "description": "List data visualizations (applications) published on this portal. Returns title, slug, and summary for each application.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Optional full-text search query"
      },
      "size": {
        "type": "number",
        "description": "Number of results to return (default 10, max 50)"
      },
      "page": {
        "type": "number",
        "description": "Page number (default 1)"
      }
    }
  },
  "page": "/"
}

{
  "name": "list_events",
  "kind": "answer",
  "impl": "imperative",
  "description": "List events published on this portal. Returns title, slug, and dates for each event.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "size": {
        "type": "number",
        "description": "Number of results to return (default 10, max 50)"
      },
      "includePast": {
        "type": "boolean",
        "description": "Include past events (default false, only upcoming events)"
      }
    }
  },
  "page": "/"
}

{
  "name": "list_news",
  "kind": "answer",
  "impl": "imperative",
  "description": "List news articles published on this portal. Returns title, slug, and date for each article.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Optional full-text search query"
      },
      "size": {
        "type": "number",
        "description": "Number of results to return (default 10, max 50)"
      }
    }
  },
  "page": "/"
}

{
  "name": "list_reuses",
  "kind": "answer",
  "impl": "imperative",
  "description": "List community reuses published on this portal. Returns title, slug, and summary for each reuse.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Optional full-text search query"
      },
      "size": {
        "type": "number",
        "description": "Number of results to return (default 10, max 50)"
      }
    }
  },
  "page": "/"
}