Skip to main content
Glama

Agréger des données

aggregate_data
Read-only

Aggregate dataset rows by 1-3 columns with an optional metric (avg, sum, min, max, value_count, cardinality). Defaults to counting rows per group. For a single global metric without grouping, use datafair_calculate_metric.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "datasetId": "<datasetId>",
      "groupByColumns": "<groupByColumns>"
    },
    "name": "aggregate_data"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoFull-text search across all columns, restricting the rows. Prefer filters for structured criteria.
bboxNoBounding box "lonMin,latMin,lonMax,latMax" (lon before lat), e.g. "-2.5,43,3,47". Geolocalized datasets only.
sortNoArray with one sort key per aggregation level: "count"/"-count" (group size), "key"/"-key" (group value), "metric"/"-metric" (metric value). Example: ["-count"].
metricNoMetric computed ON EACH GROUP. Omit to count rows per group.
filtersNoColumn filters { "<column key><suffix>": "<value as a string>" }, e.g. { "ville_eq": "Paris", "age_lte": "30", "nom_search": "Jean" }. Suffixes: _eq _neq _in _nin (comma-separated) _gt _gte _lt _lte _starts _exists _nexists _search (words, the default for text) _contains (when enabled). A rejected suffix answers a 400 listing the column's. Never prefix with _c_.
datasetIdYesThe "id" of a datafair_list_account_datasets result, not its title or slug.
dateMatchNoDate "YYYY-MM-DD" (single day) or "YYYY-MM-DD,YYYY-MM-DD" (range), e.g. "2023-11-21". Temporal datasets only.
geoDistanceNoProximity filter "lon,lat,distance" (lon first), e.g. "2.35,48.85,10km"; distance "0" = point-in-polygon. Geolocalized datasets only.
metricColumnNoThe column to compute the metric on, for the average or sum of that column. Requires metric.
groupByColumnsYesColumns to GROUP BY (like SQL GROUP BY), 1 to 3 keys from datafair_describe_dataset. NOT the column to compute the metric on.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changed
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedInput schema / properties / bbox / examples
      Added value: +[
      +  "2.2241,48.8156,2.4699,48.9022"
      +]
    • changedInput schema / properties / datasetId / description
      Previous value: -"The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."New value: +"The \"id\" of a datafair_list_account_datasets result, not its title or slug."
    • removedInput schema / properties / filters / additionalProperties
      Removed value: -{
      -  "type": "string"
      -}
    • changedInput schema / properties / filters / description
      Previous value: -"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)."New value: +"Column filters { \"<column key><suffix>\": \"<value as a string>\" }, e.g. { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes: _eq _neq _in _nin (comma-separated) _gt _gte _lt _lte _starts _exists _nexists _search (words, the default for text) _contains (when enabled). A rejected suffix answers a 400 listing the column's. Never prefix with _c_."
    • addedInput schema / properties / filters / patternProperties
      Added value: +{
      +  ".*": {
      +    "default": "",
      +    "type": "string"
      +  }
      +}
    • removedInput schema / properties / filters / propertyNames
      Removed value: -{
      -  "pattern": "^.+_(search|eq|neq|in|nin|starts|contains|gte?|lte?|n?exists)$"
      -}
    • changedInput schema / properties / groupByColumns / description
      Previous value: -"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)."New value: +"Columns to GROUP BY (like SQL GROUP BY), 1 to 3 keys from datafair_describe_dataset. NOT the column to compute the metric on."
    • removedInput schema / properties / groupByColumns / maxItems
      Removed value: -3
    • removedInput schema / properties / groupByColumns / minItems
      Removed value: -1
    • removedInput schema / properties / metric / additionalProperties
      Removed value: -false
    • changedInput schema / properties / metric / description
      Previous value: -"Optional metric to compute ON EACH GROUP. If not provided, defaults to counting rows per group."New value: +"Metric computed ON EACH GROUP. Omit to count rows per group."
    • addedInput schema / properties / metric / enum
      Added value: +[
      +  "avg",
      +  "sum",
      +  "min",
      +  "max",
      +  "cardinality",
      +  "value_count"
      +]
    • removedInput schema / properties / metric / properties
      Removed value: -{
      -  "column": {
      -    "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": "string"
      -  },
      -  "type": {
      -    "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).",
      -    "enum": [
      -      "sum",
      -      "avg",
      -      "min",
      -      "max",
      -      "count"
      -    ],
      -    "type": "string"
      -  }
      -}
    • removedInput schema / properties / metric / required
      Removed value: -[
      -  "column",
      -  "type"
      -]
    • changedInput schema / properties / metric / type
      Previous value: -"object"New value: +"string"
    • addedInput schema / properties / metricColumn
      Added value: +{
      +  "description": "The column to compute the metric on, for the average or sum of that column. Requires metric.",
      +  "type": "string"
      +}
    • addedInput schema / properties / q
      Added value: +{
      +  "description": "Full-text search across all columns, restricting the rows. Prefer filters for structured criteria.",
      +  "maxLength": 1000,
      +  "type": "string"
      +}
    • changedInput schema / properties / sort / description
      Previous value: -"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"New value: +"Array with one sort key per aggregation level: \"count\"/\"-count\" (group size), \"key\"/\"-key\" (group value), \"metric\"/\"-metric\" (metric value). Example: [\"-count\"]."
    • addedInput schema / properties / sort / items
      Added value: +{
      +  "type": "string"
      +}
    • changedInput schema / properties / sort / type
      Previous value: -"string"New value: +"array"
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "http://json-schema.org/draft-07/schema#",
      -  "additionalProperties": false,
      -  "properties": {
      -    "aggs": {
      -      "description": "Array of aggregation results for each group (limited to 20 rows)",
      -      "type": "array"
      -    },
      -    "datasetId": {
      -      "description": "The dataset ID that was aggregated",
      -      "type": "string"
      -    },
      -    "requestUrl": {
      -      "description": "Direct URL to API results in JSON format (must be included in responses for citation and direct access to aggregated view)",
      -      "type": "string"
      -    },
      -    "total": {
      -      "description": "The total number of rows in the dataset",
      -      "type": "number"
      -    },
      -    "total_other": {
      -      "description": "Number of rows NOT included in the returned aggregations (only the top groups are returned). Add this to the sum of all group totals to reconstruct the dataset total.",
      -      "type": "number"
      -    },
      -    "total_values": {
      -      "description": "The total number of different values aggregated across all specified columns",
      -      "type": "number"
      -    }
      -  },
      -  "required": [
      -    "datasetId",
      -    "total",
      -    "total_values",
      -    "total_other",
      -    "requestUrl",
      -    "aggs"
      -  ],
      -  "type": "object"
      -}New value: +null
  2. Changed12 schema fields changed
    • changedInput schema / properties / bbox / description
      Previous value: -"Geographic bounding box filter (only for geolocalized datasets). Format: \"lonMin,latMin,lonMax,latMax\". Example: \"-2.5,43,3,47\"."New value: +"Bounding box \"lonMin,latMin,lonMax,latMax\" (lon before lat), e.g. \"-2.5,43,3,47\". Geolocalized datasets only."
    • changedInput schema / properties / datasetId / description
      Previous value: -"The exact dataset ID from the \"id\" field in search_datasets results. Do not use the title or slug."New value: +"The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
    • changedInput schema / properties / dateMatch / description
      Previous value: -"Temporal filter (only for temporal datasets with date fields). Accepts a single date \"YYYY-MM-DD\" to match that day, or a date range \"YYYY-MM-DD,YYYY-MM-DD\" to match an overlapping period. ISO datetimes also accepted. Example: \"2023-11-21\" or \"2023-01-01,2023-12-31\"."New value: +"Date \"YYYY-MM-DD\" (single day) or \"YYYY-MM-DD,YYYY-MM-DD\" (range), e.g. \"2023-11-21\". Temporal datasets only."
    • changedInput schema / properties / filters / description
      Previous value: -"Column filters as key-value pairs. Key format: column_key + suffix (see server instructions for available suffixes). All values must be strings, even for numbers/dates. If a column key has underscores (e.g., code_postal), just append the suffix: code_postal_eq. Example: { \"nom_search\": \"Jean\", \"age_lte\": \"30\", \"ville_eq\": \"Paris\" }"New value: +"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)."
    • changedInput schema / properties / geoDistance / description
      Previous value: -"Geographic proximity filter (only for geolocalized datasets). Restricts results to within a distance from a point. Format: \"lon,lat,distance\". Example: \"2.35,48.85,10km\". Use distance \"0\" for point-in-polygon containment."New value: +"Proximity filter \"lon,lat,distance\" (lon first), e.g. \"2.35,48.85,10km\"; distance \"0\" = point-in-polygon. Geolocalized datasets only."
    • removedOutput schema / properties / aggregations
      Removed value: -{
      -  "description": "Array of aggregation results for each specified column (limited to 20 rows)",
      -  "items": {
      -    "additionalProperties": false,
      -    "properties": {
      -      "aggregations": {
      -        "description": "Nested aggregation results when multiple columns are specified (max 3 levels deep)",
      -        "items": {
      -          "$ref": "#/properties/aggregations/items"
      -        },
      -        "type": "array"
      -      },
      -      "columnValue": {
      -        "description": "The value of the aggregated column (string or number)",
      -        "type": [
      -          "string",
      -          "number"
      -        ]
      -      },
      -      "metricValue": {
      -        "description": "The value of the aggregation metric (e.g., sum, avg) on the selected column",
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "nonRepresented": {
      -        "description": "Number of rows NOT included in the returned aggregations for this column (only top groups are returned)",
      -        "type": "number"
      -      },
      -      "total": {
      -        "description": "Total number of rows aggregated for this column",
      -        "type": "number"
      -      },
      -      "totalAggregated": {
      -        "description": "Total number of different values aggregated for this column",
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "total",
      -      "columnValue"
      -    ],
      -    "type": "object"
      -  },
      -  "type": "array"
      -}
    • addedOutput schema / properties / aggs
      Added value: +{
      +  "description": "Array of aggregation results for each group (limited to 20 rows)",
      +  "type": "array"
      +}
    • removedOutput schema / properties / nonRepresented
      Removed value: -{
      -  "description": "Number of rows NOT included in the returned aggregations (only the top 20 groups are returned). Add this to the sum of all group totals to reconstruct the dataset total.",
      -  "type": "number"
      -}
    • removedOutput schema / properties / totalAggregated
      Removed value: -{
      -  "description": "The total number of different values aggregated across all specified columns",
      -  "type": "number"
      -}
    • addedOutput schema / properties / total_other
      Added value: +{
      +  "description": "Number of rows NOT included in the returned aggregations (only the top groups are returned). Add this to the sum of all group totals to reconstruct the dataset total.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / total_values
      Added value: +{
      +  "description": "The total number of different values aggregated across all specified columns",
      +  "type": "number"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "total",
      -  "totalAggregated",
      -  "nonRepresented",
      -  "datasetId",
      -  "requestUrl",
      -  "aggregations"
      -]New value: +[
      +  "datasetId",
      +  "total",
      +  "total_values",
      +  "total_other",
      +  "requestUrl",
      +  "aggs"
      +]
  3. Changed3 schema fields changed
    • addedInput schema / properties / bbox
      Added value: +{
      +  "description": "Geographic bounding box filter (only for geolocalized datasets). Format: \"lonMin,latMin,lonMax,latMax\". Example: \"-2.5,43,3,47\".",
      +  "type": "string"
      +}
    • addedInput schema / properties / dateMatch
      Added value: +{
      +  "description": "Temporal filter (only for temporal datasets with date fields). Accepts a single date \"YYYY-MM-DD\" to match that day, or a date range \"YYYY-MM-DD,YYYY-MM-DD\" to match an overlapping period. ISO datetimes also accepted. Example: \"2023-11-21\" or \"2023-01-01,2023-12-31\".",
      +  "type": "string"
      +}
    • addedInput schema / properties / geoDistance
      Added value: +{
      +  "description": "Geographic proximity filter (only for geolocalized datasets). Restricts results to within a distance from a point. Format: \"lon,lat,distance\". Example: \"2.35,48.85,10km\". Use distance \"0\" for point-in-polygon containment.",
      +  "type": "string"
      +}
  4. Changed10 schema fields changed
    • removedInput schema / properties / aggregation
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "The aggregation specification to perform on the specified column. Use keys from describe_dataset. If not provided, defaults to counting unique values in the aggregation column.",
      -  "properties": {
      -    "column": {
      -      "description": "The column key to aggregate (use keys from describe_dataset)",
      -      "type": "string"
      -    },
      -    "metric": {
      -      "description": "Aggregation metric to perform on the column. Available operations are: sum, avg, min, max, count.",
      -      "enum": [
      -        "sum",
      -        "avg",
      -        "min",
      -        "max",
      -        "count"
      -      ],
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "column",
      -    "metric"
      -  ],
      -  "type": "object"
      -}
    • removedInput schema / properties / aggregationColumns
      Removed value: -{
      -  "description": "List of column keys to aggregate (use keys from describe_dataset, min 1 column, max 3 columns)",
      -  "items": {
      -    "type": "string"
      -  },
      -  "maxItems": 3,
      -  "minItems": 1,
      -  "type": "array"
      -}
    • changedInput schema / properties / datasetId / description
      Previous value: -"The unique dataset ID obtained from search_datasets tool"New value: +"The exact dataset ID from the \"id\" field in search_datasets results. Do not use the title or slug."
    • changedInput schema / properties / filters / description
      Previous value: -"Column filters as key-value pairs. Key format: column_key + suffix (see server instructions for available suffixes). Example: { \"nom_search\": \"Jean\", \"age_lte\": \"30\", \"ville_eq\": \"Paris\" }"New value: +"Column filters as key-value pairs. Key format: column_key + suffix (see server instructions for available suffixes). All values must be strings, even for numbers/dates. If a column key has underscores (e.g., code_postal), just append the suffix: code_postal_eq. Example: { \"nom_search\": \"Jean\", \"age_lte\": \"30\", \"ville_eq\": \"Paris\" }"
    • addedInput schema / properties / groupByColumns
      Added value: +{
      +  "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).",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 3,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / metric
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Optional metric to compute ON EACH GROUP. If not provided, defaults to counting rows per group.",
      +  "properties": {
      +    "column": {
      +      "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": "string"
      +    },
      +    "type": {
      +      "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).",
      +      "enum": [
      +        "sum",
      +        "avg",
      +        "min",
      +        "max",
      +        "count"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "column",
      +    "type"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / sort
      Added value: +{
      +  "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",
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "datasetId",
      -  "aggregationColumns"
      -]New value: +[
      +  "datasetId",
      +  "groupByColumns"
      +]
    • changedOutput schema / properties / aggregations / items / properties / nonRepresented / description
      Previous value: -"The number of non-represented rows for this column"New value: +"Number of rows NOT included in the returned aggregations for this column (only top groups are returned)"
    • changedOutput schema / properties / nonRepresented / description
      Previous value: -"The number of non-represented rows in the dataset, 0 if totalAggregated is less than 20, otherwise the number of non-represented rows"New value: +"Number of rows NOT included in the returned aggregations (only the top 20 groups are returned). Add this to the sum of all group totals to reconstruct the dataset total."
  5. First observed

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), and the description adds real behavioral context on top: aggregation happens per group, the metric is computed on each group, and omitting the metric falls back to row counting. It stops short of describing the returned result shape or pagination, but there is no mutation risk to disclose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core behavior first and the sibling escape hatch second. The parenthetical enum list is compact and directly actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with nested filters and no output schema, the description covers purpose and the main alternative but never says what comes back (grouped keys plus count/metric values) or anything about result size. An agent can call it correctly, but is guessing about the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds a genuine clarification beyond it: the default behavior when metric is omitted and the explicit note that grouping is per level. It still leaves the interaction of sort levels and metricColumn/groupByColumns pairing to the schema, which already handles it well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (aggregate dataset rows) plus the exact shape of the operation: 1-3 grouping columns, an optional metric drawn from a named enum, and a row-count default. That is enough to distinguish it from search_data or calculate_metric 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.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the ungrouped single-metric case to datafair_calculate_metric, which is the key exclusion an agent needs. It does not mention that groupByColumns must come from a prior describe_dataset call (that hint lives only in the schema), so guidance is clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources