cbs-open-data_mcp: Instructions file for GitHub Copilot

CBS Open Data MCP – Usage Guide

Dataset Discovery

• Always use filter with contains(Title,'...') or contains(Description,'...') — never use search/$search (returns popularity-ranked, irrelevant results).
• Use Title search when the topic keyword likely appears in table titles; use Description search when the keyword is domain-specific and may only appear in the table description.
• Use singular search terms — CBS descriptions contain both singular and plural forms, so searching both is redundant.
• Use specific terms; generic terms like 'energie' or 'verbruik' return large, unfocused result sets.
• Combine filters for precision: contains(Title,'energie') and (Status ne 'Gediscontinueerd').
• Discontinued datasets are excluded by default.

Recommended Workflow

1. query_datasets(filter="contains(Title,'keyword')") → start with a single validation call (no parallel, no select) to find relevant table IDs and check ObservationCount.
2. (Optional) Explore structure when dimension names or measure units are unknown:
   • get_dimensions(dataset="IDHERE") → dimension names and available codes.
   • get_measure_codes(dataset="IDHERE") → measure identifiers and units.
3. Choose fetching strategy based on ObservationCount:
   • < 10.000 obs: get_observations() — auto-paginates, fetches everything.
   • ≥ 10.000 obs: query_observations(filter="...") — applies server-side filtering. Always prefer this for large datasets.
4. If multiple candidate datasets exist (e.g. actueel vs. prognose), prefer the smallest one that still answers the question — server-side filtering on large CBS datasets is unreliable.

Parameter Naming

• The dataset parameter is always called dataset (not id).
• The catalog parameter defaults to "CBS" — omit unless querying a different catalog.
• Omit select unless you know the exact field names; unknown field names in select cause a 400 error. If you need select, introduce it only after a successful baseline query.