idescat.cat

{
  "name": "get_viewing_categories",
  "kind": "answer",
  "impl": "imperative",
  "description": "Use this tool priority if you want to change the state of some categories and you want to check if they are currently available. Returns active categories visible in the table for target dimensions. Defaults to all dataset dimensions if omitted.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dimensionIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Optional array of dimension IDs to query (e.g. ['TEMPS', 'SEXE'])."
      }
    }
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "select_categories_batch",
  "kind": "act",
  "impl": "imperative",
  "description": "Priorize this tool if data to select is available at the table. Select or toggle categories across dimensions. Use mode='replace' (default) to replace current selection, or mode='toggle' to flip individual states.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "selections": {
        "type": "object",
        "description": "Map of dimension IDs to array of category IDs (e.g. {'TEMPS': ['2023', '2024']}).",
        "additionalProperties": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "mode": {
        "type": "string",
        "enum": [
          "replace",
          "toggle"
        ],
        "description": "if you want to change just some categories or options use 'toggle'. It will set the value you chose to the chosen category. Use 'replace' when you want to set a specific view with the current available categories and remove the current view."
      },
      "dataMode": {
        "type": "string",
        "enum": [
          "table",
          "metadata"
        ],
        "description": "'table' uses active table categories. 'metadata' uses complete dataset categories. Do NOT call 'confirm_dataset_filters' if 'table' mode used."
      }
    },
    "required": [
      "selections",
      "mode",
      "dataMode"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "get_dimensions",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns a complete list of all available dataset dimensions including their unique IDs and descriptive names.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "get_categories_by_dimensions",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns categories and selection status for multiple dimensions. Protocol: Call this first to check if the target categories exist in the current view. If the desired category is present in the returned list, do NOT proceed with `switch_dataset_view_mode` directly. IMPORTANT: If 'selected' is 0, it means ALL categories are active. DO NOT use `select_categories_batch` to select all if 'selected' is 0.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dimensionIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Optional array of dimension IDs to filter (e.g. ['TEMPS', 'SEXE']). If omitted or empty, returns all dataset dimensions."
      },
      "source": {
        "type": "string",
        "enum": [
          "dataset",
          "metadata"
        ],
        "description": "Source data structure. Use 'dataset' for DATASET.ds or 'metadata' for ESTAT.data.meta.",
        "default": "dataset"
      }
    }
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "toggle_all_categories_batch",
  "kind": "act",
  "impl": "imperative",
  "description": "Selects or deselects all categories simultaneously for multiple dimensions.Note: If a dimension ends up with 0 elements selected, system defaults to selecting all elements.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "toggles": {
        "type": "object",
        "description": "Map of dimension IDs to selection state. Key: dimension ID (e.g., 'TEMPS', 'SEXE'). Value: true to select all categories, false to deselect all.",
        "additionalProperties": {
          "type": "boolean"
        }
      }
    },
    "required": [
      "toggles"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "configure_dimension_display_labels_batch",
  "kind": "act",
  "impl": "imperative",
  "description": "Configures category display representations (showing codes, names/labels, or both) for multiple dimensions in batch.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "configurations": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "dimensionId": {
              "type": "string",
              "description": "Target dimension ID (e.g., 'TEMPS', 'SEXE')."
            },
            "showCodes": {
              "type": "boolean",
              "description": "True to display category ID codes."
            },
            "showNames": {
              "type": "boolean",
              "description": "True to display category descriptive names/labels."
            }
          },
          "required": [
            "dimensionId",
            "showCodes",
            "showNames"
          ]
        }
      }
    },
    "required": [
      "configurations"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "move_dimension_position_batch",
  "kind": "act",
  "impl": "imperative",
  "description": "Shifts the relative structural position (ordering) of multiple dimensions in a single request using direction steps: 'up_left' (shifts dimension towards top/left) or 'down_right' (shifts dimension towards bottom/right).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "moves": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "dimensionId": {
              "type": "string",
              "description": "Target dimension ID (e.g., 'TEMPS', 'SEXE')."
            },
            "direction": {
              "type": "string",
              "enum": [
                "up_left",
                "down_right"
              ],
              "description": "Direction to move dimension position."
            }
          },
          "required": [
            "dimensionId",
            "direction"
          ]
        },
        "description": "List of dimension move operations."
      }
    },
    "required": [
      "moves"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "download_dataset",
  "kind": "act",
  "impl": "imperative",
  "description": "Triggers file download (excel, json, csv) with configuration. EXPLICIT ONLY when user explicitly asks for a file download. Otherwise NEVER use this tool.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tipus": {
        "type": "string",
        "enum": [
          "excel",
          "json",
          "csv"
        ],
        "description": "Target file export format."
      },
      "config": {
        "type": "object",
        "properties": {
          "conjunt": {
            "type": "string",
            "enum": [
              "taula",
              "tot"
            ],
            "description": "Export current filtered view ('taula') or entire dataset ('tot'). Default: 'taula'."
          },
          "formatExcel": {
            "type": "string",
            "enum": [
              ".xlsx",
              ".ods",
              ".txt"
            ],
            "description": "File extension for excel export. Default: '.xlsx'."
          },
          "estructuraJson": {
            "type": "string",
            "enum": [
              "jsonStat",
              "jsonFileres",
              "jsonColumnes"
            ],
            "description": "Structure format for JSON export. Default: 'jsonStat'."
          },
          "delimitadorCsv": {
            "type": "string",
            "enum": [
              "coma",
              "semicolon",
              "tab"
            ],
            "description": "Delimiter character for CSV export."
          },
          "separadorDecimal": {
            "type": "string",
            "enum": [
              "coma",
              "punt"
            ],
            "description": "Decimal point separator for CSV export."
          },
          "etiquetes": {
            "type": "string",
            "enum": [
              "id",
              "label",
              "idlabel"
            ],
            "description": "Category representation mode in export."
          },
          "enriquir": {
            "type": "boolean",
            "description": "Enrich export with additional metadata attributes."
          },
          "transposarPer": {
            "type": "string",
            "description": "Dimension ID to pivot/transpose data by."
          }
        }
      }
    },
    "required": [
      "tipus"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "toggle_view_options",
  "kind": "act",
  "impl": "imperative",
  "description": "Enables or disables visual table display options: 'percent' (calculates and displays percentage values), 'estat' (shows or hides data quality/status flags in cells), or 'nodata' (hides empty table rows with no data values). Requires being in table data view.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "opcio": {
        "type": "string",
        "enum": [
          "percent",
          "estat",
          "nodata"
        ],
        "description": "Display option to toggle: 'percent' (percentage calculation), 'estat' (status flags), or 'nodata' (suppress empty rows)."
      },
      "actiu": {
        "type": "boolean",
        "description": "Desired state: true to enable the option, false to disable it."
      }
    },
    "required": [
      "opcio",
      "actiu"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "change_dimensions_axis_batch",
  "kind": "act",
  "impl": "imperative",
  "description": "Reorganizes table structure by moving specified dimensions between rows and columns in batch.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "axes": {
        "type": "object",
        "description": "Map of dimension IDs to target axis assignment. Key: dimension ID (e.g., 'SEXE', 'EDAT', 'TEMPS'). Value: 'row' (move to rows) or 'column' (move to columns).",
        "additionalProperties": {
          "type": "string",
          "enum": [
            "row",
            "column"
          ]
        }
      }
    },
    "required": [
      "axes"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "change_dimensions_order_batch",
  "kind": "transact",
  "impl": "imperative",
  "description": "Changes the internal sorting direction (ascending/descending) for categories within multiple dimensions in a single request. Primary use is reversing or setting temporal/ordinal dimension directions.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orders": {
        "type": "object",
        "description": "Map of dimension IDs to target sort directions. Key: dimension ID (e.g., 'TEMPS', 'EDAT'). Value: 'asc' (ascending) or 'desc' (descending).",
        "additionalProperties": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        }
      }
    },
    "required": [
      "orders"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "set_last_periods_batch",
  "kind": "act",
  "impl": "imperative",
  "description": "Enables, disables, or changes the 'last N periods' dynamic filter for time dimensions. Accepts a batch array of period settings.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "periods": {
        "type": "array",
        "description": "Array of period configurations per time dimension.",
        "items": {
          "type": "object",
          "properties": {
            "dimensionId": {
              "type": "string",
              "description": "Identifier of the time dimension (e.g., 'YEAR', 'MONTH')."
            },
            "actiu": {
              "type": "boolean",
              "description": "Set true to activate the 'last N periods' filter, false to disable it."
            },
            "quantitat": {
              "type": "integer",
              "description": "Number N of recent periods to select (e.g., 5 for last 5 periods). Mandatory if 'actiu' is true."
            }
          },
          "required": [
            "dimensionId",
            "actiu"
          ]
        }
      }
    },
    "required": [
      "periods"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "sort_table_by_column",
  "kind": "act",
  "impl": "imperative",
  "description": "Sorts dataset rows by a specific column in ascending, descending, or original order. MUST call 'get_sortable_data_by_column' first to resolve 'columnIndex'. Fails if table has multiple row dimensions or if row dimension is temporal.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "columnIndex": {
        "type": "integer",
        "description": "Zero-based index of the sortable column, obtained from 'get_sortable_data_by_column'."
      },
      "targetState": {
        "type": "string",
        "enum": [
          "asc",
          "desc",
          "none"
        ],
        "description": "Desired sort direction: 'asc' (ascending), 'desc' (descending), or 'none' (reset sorting)."
      }
    },
    "required": [
      "columnIndex",
      "targetState"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "get_sortable_data_by_column",
  "kind": "answer",
  "impl": "imperative",
  "description": "Retrieves metadata (index, HTML id, headers, period/year) for all sortable table columns. MUST be called prior to 'sort_table_by_column' to resolve the required zero-based columnIndex.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "filter_geographic_dimension",
  "kind": "act",
  "impl": "imperative",
  "description": "Filters geographic categories by text query for Province (PROV) or Comarca (COM) dimensions. Does NOT auto-select items—only filters visibility. NOT valid for Municipalities (MUN). Returns matched category IDs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search text to filter regions (e.g., 'Barcelona', 'Barcelonès'). Pass empty string to clear filter."
      }
    },
    "required": [
      "query"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "get_available_divisions",
  "kind": "answer",
  "impl": "imperative",
  "description": "Retrieves list of available alternative geographic and temporal divisions (e.g. mun, prov) for the current dataset. Use this BEFORE calling 'switch_division' to discover valid 'ambit' codes. Only available in table data view.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "switch_division",
  "kind": "act",
  "impl": "imperative",
  "description": "Switches the active dataset view to a different geographic dimension or temporal series. MUST be used when data needs to be retrieved for a specific region or time frame available in 'related' links. Modifies the underlying dataset context. Do not call more tools if you don't have to apply changes.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "ambit": {
        "type": "string",
        "description": "Technical identifier code key matching a valid related link (e.g., 'mun', 'com' or specific series code)."
      }
    },
    "required": [
      "ambit"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "switch_dataset_view_mode",
  "kind": "act",
  "impl": "imperative",
  "description": "Use this tool ONLY if you have cannot satisfied the demand using 'select_categories_batch'. Use this tool ONLY as a last resort when the target categories are NOT available in the current table view (verify this via 'get_categories_by_dimensions'). Protocol: 1. Call 'get_categories_by_dimensions'. 2. Always attempt to perform operations (like 'select_categories_batch') on the existing table view first. 3. If the data is missing, ONLY THEN call `switch_dataset_view_mode(mode='metadata')`. 4. After applying changes in metadata mode (so, after need to call 'switch_dataset_view_mode', and only then), you MUST use 'confirm_dataset_filters' to return to 'table' mode and persist the changes. DO NOT switch to metadata mode for routine operations or if the categories are already visible in the table.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "mode": {
        "type": "string",
        "enum": [
          "table",
          "metadata"
        ],
        "description": "Target view mode."
      }
    },
    "required": [
      "mode"
    ]
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "confirm_dataset_filters",
  "kind": "act",
  "impl": "imperative",
  "description": "Can ONLY be called if previously 'switch_dataset_view_mode' has been called successfuly. Applies selected metadata filters and switches view mode to data table. MUST be called after modifying dimension/variable filters to fetch filtered data (when we are in metadata mode. NEVER when table mode). Fails if view is already in table mode or if selection exceeds maximum allowed observations. In this case, you have to reduce the number observations until check_obs tool succeeds.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}

{
  "name": "check_obs",
  "kind": "answer",
  "impl": "imperative",
  "description": "Call this function before call 'confirm_dataset_filters', only in 'metadata' mode. If succeed, go on. If not, reduce the amount of data you are selecting to show in 'table' mode.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  },
  "page": "/pub/?id=censph&n=16354&lang=en"
}