How do I use Catalunya Open Data MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Catalunya Open Data MCP find datasets about air quality in Barcelona" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Catalunya Open Data MCP

by aalises

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Remote

Catalunya Open Data MCP

A read-only Model Context Protocol server for discovering, describing, and querying public datasets from Catalunya.

The server currently supports the Generalitat de Catalunya open data portal powered by Socrata, IDESCAT Tables v2, and Open Data BCN. It exposes small, reliable workflows: search or browse catalogs, inspect schemas or dimensions, query bounded extracts, run BCN geospatial scans, preview safe CSV/JSON downloads, and keep enough provenance to cite the source cleanly.

Why This Exists

Open data portals are rich, but they are not always pleasant to explore from a chat interface. This server gives MCP clients a structured way to answer questions such as:

"Find datasets about housing starts and completions."
"Which fields can I query in this dataset?"
"Show the latest rows for Girona, using valid API field names."
"Preview Barcelona street-tree data or query DataStore-active city equipment."
"Count tree species on Carrer Consell de Cent or find facilities near a coordinate."
"Create a citation for the dataset and include the source URL."

Every data-returning tool includes provenance, response caps, and structured errors so the model can recover from bad filters instead of guessing.

For copy-paste task examples, see COOKBOOK.md.

Related MCP server: Datos.gob.es-MCP

Requirements

Node.js 22.12 or newer
npm 10 or newer

Install

npm install
npm run build

This is a local stdio MCP server. In normal use, your MCP client starts dist/index.js and communicates with it over stdin/stdout.

Connect an MCP Client

After building, add a stdio server entry like this to your MCP client configuration:

{
  "mcpServers": {
    "catalunya-opendata": {
      "command": "node",
      "args": ["/absolute/path/to/catalunya-opendata-mcp/dist/index.js"]
    }
  }
}

For active development, point the client at the TypeScript watcher instead:

{
  "mcpServers": {
    "catalunya-opendata": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/absolute/path/to/catalunya-opendata-mcp"
    }
  }
}

The built node dist/index.js path is the most predictable setup for day-to-day use. The watcher is useful while changing the server.

MCP Surface

Tools

Tool	Purpose
`ping`	Check that the server is running.
`socrata_search_datasets`	Search the Catalunya Socrata catalog and return dataset IDs, titles, web URLs, API endpoints, update times, and provenance.
`socrata_describe_dataset`	Fetch dataset metadata, license or terms, timestamps, attribution, and queryable column `field_name` values.
`socrata_query_dataset`	Query dataset rows with raw SODA clause values: `select`, `where`, `group`, `order`, `limit`, and `offset`.
`idescat_search_tables`	Search the committed IDESCAT Tables v2 index and return table IDs plus hierarchy labels. Geography words and named places are mapped to `geo_candidates`. For exhaustive discovery, use `idescat_list_*` to browse statistics, nodes, tables, and geos directly from IDESCAT.
`idescat_list_statistics`	List top-level IDESCAT statistics.
`idescat_list_nodes`	List nodes under an IDESCAT statistic.
`idescat_list_tables`	List tables under an IDESCAT statistic node.
`idescat_list_table_geos`	List territorial divisions available for an IDESCAT table.
`idescat_get_table_metadata`	Fetch IDESCAT JSON-stat metadata: dimensions, category IDs, filter guidance, sources, links, and provenance.
`idescat_get_table_data`	Fetch a bounded flattened data extract using IDESCAT dimension/category filters and `_LAST_`.
`bcn_recommend_resources`	Recommend high-value Open Data BCN resources for natural-language city questions such as trees on a street, facilities near a place, or district/neighborhood area queries.
`bcn_plan_query`	Plan a natural-language Barcelona city question into resource, place-resolution, geo-query, and citation steps without running the final data query.
`bcn_execute_city_query`	Execute a ready BCN city-query plan end-to-end with the same bounded helper tools, blocking when a resource or place choice is ambiguous.
`bcn_answer_city_query`	Execute a ready BCN city-query plan and return deterministic `answer_text`, `answer_markdown`, blocked-case `selection_options`, map-ready `summary.map_points`, warning `caveats`, informational `execution_notes`, citation guidance, selected resource metadata, and the raw final result.
`bcn_search_packages`	Search Open Data BCN CKAN packages for Barcelona city datasets such as street trees, facilities, equipment, mobility, and services.
`bcn_get_package`	Fetch one Open Data BCN package with resource IDs, formats, DataStore activity, package license, and provenance.
`bcn_get_resource_info`	Inspect one Open Data BCN resource. Active DataStore resources include queryable fields.
`bcn_query_resource`	Query an active Open Data BCN CKAN DataStore resource with structured filters and bounded POST responses.
`bcn_resolve_place`	Resolve Barcelona place names to source-bounded WGS84 coordinate candidates and district/neighborhood `area_ref` metadata for follow-up geo queries.
`bcn_query_resource_geo`	Query BCN resources with latitude/longitude columns using `near`, `bbox`, `within_place`, street/name `contains`, and optional `group_by` counts.
`bcn_preview_resource`	Fetch a safe bounded CSV/JSON preview for non-DataStore Open Data BCN resources.

Prompts

Prompt	Purpose
`socrata_query_workflow`	Guides a search -> describe -> query flow and reminds clients to use returned `field_name` values.
`socrata_citation`	Builds a concise citation from described dataset metadata or the metadata resource.
`idescat_query_workflow`	Guides an IDESCAT search/browse -> geos -> metadata -> bounded data flow.
`idescat_citation`	Builds a concise citation from IDESCAT table metadata.
`bcn_query_workflow`	Guides an Open Data BCN package -> resource -> query/preview flow.
`bcn_citation`	Builds a concise citation from Open Data BCN package or resource metadata.

Resources

Resource	Purpose
`catalunya-opendata://about`	Short server metadata.
`socrata://datasets/{source_id}/metadata`	Dataset schema and provenance metadata, matching `socrata_describe_dataset.data`.
`idescat://tables/{statistics_id}/{node_id}/{table_id}/{geo_id}/metadata`	IDESCAT table metadata artifact, matching `idescat_get_table_metadata.data`.
`bcn://packages/{package_id}`	Open Data BCN package metadata, matching `bcn_get_package.data`.
`bcn://resources/{resource_id}/schema`	Open Data BCN resource metadata and DataStore fields, matching `bcn_get_resource_info.data`.

Socrata Workflow

Use the tools in this order when answering data questions.

1. Search

Call socrata_search_datasets with the user's topic:

{
  "query": "Habitatges iniciats acabats",
  "limit": 10
}

Each result includes a source_id, web_url, api_endpoint, update timestamp, and provenance. Keep the source_id for the next step.

2. Describe

Call socrata_describe_dataset before writing filters or selecting columns:

{
  "source_id": "j8h8-vxug"
}

Use the returned columns[].field_name values in SODA clauses. Do not use display names, translated labels, or column names with spaces unless they are returned as field_name.

3. Query

Pass clause values only. Do not include URL fragments such as ?$where=.

{
  "source_id": "j8h8-vxug",
  "select": "municipi, comarca_2023, any",
  "where": "municipi = 'Girona'",
  "order": "municipi, any",
  "limit": 10
}

For stable pagination, always include order when using offset:

{
  "source_id": "j8h8-vxug",
  "select": "municipi, comarca_2023, any",
  "order": "municipi, any",
  "limit": 25,
  "offset": 50
}

For aggregate queries, combine aggregate functions in select with group:

{
  "source_id": "j8h8-vxug",
  "select": "comarca_2023, count(*) as total",
  "group": "comarca_2023",
  "order": "total desc",
  "limit": 10
}

4. Attach Metadata

When your MCP client supports resources, attach the dataset metadata directly:

socrata://datasets/j8h8-vxug/metadata

The resource body is the dataset metadata object itself, without the tool-call envelope. It is useful context for follow-up queries and citations.

5. Cite

Use socrata_citation with socrata_describe_dataset output or the metadata resource. A concise citation should include the dataset title, attribution, source domain or URL, last updated timestamp, and license or terms when available.

IDESCAT Workflow

Use idescat_search_tables for topic discovery, or browse with idescat_list_statistics, idescat_list_nodes, and idescat_list_tables. Search can recognize geography words such as comarca, municipi, municipal, and provincia, plus named places such as Maresme, Barcelonès, and Girona; prefer results whose geo_candidates include the requested geography, then confirm the geo_id with idescat_list_table_geos. It also handles common semantic aliases such as taxa atur, paro, renda per capita Maresme, and poblacio municipal without changing the tool inputs. Every metadata and data request requires a territorial division, so call idescat_list_table_geos before fetching a table.

IDESCAT support is scoped to Tables v2. Idescat topic pages may list inactive statistics, additional statistics, or statistics from other organisms that are not exposed through this connector.

Named-place workflow example:

{
  "query": "renda per capita Maresme",
  "lang": "ca",
  "limit": 5
}

After choosing an RFDBC result with com in geo_candidates, call idescat_list_table_geos and select geo_id: "com". Then pass the original place phrase into metadata:

{
  "statistics_id": "rfdbc",
  "node_id": "13302",
  "table_id": "21197",
  "geo_id": "com",
  "lang": "ca",
  "place_query": "Maresme"
}

When filter_guidance.recommended_data_call is present, use it as the starting point for idescat_get_table_data; it contains only actual metadata category IDs and neutral defaults such as TOTAL or single-category dimensions.

Call idescat_get_table_metadata before querying. Use the returned dimension IDs and category IDs in idescat_get_table_data.filters, and use last to request the latest time periods:

{
  "statistics_id": "pmh",
  "node_id": "1180",
  "table_id": "8078",
  "geo_id": "com",
  "lang": "en",
  "filters": {
    "COM": ["01", "TOTAL"],
    "SEX": "F"
  },
  "last": 2,
  "limit": 20
}

IDESCAT data tools are for bounded extracts, not exhaustive table export. If the upstream API returns narrow_filters, reduce dimensions with filters or _LAST_. For citations, use idescat_get_table_metadata or the IDESCAT metadata resource; search/list operation provenance is only an operation trace.

To manually verify the live IDESCAT journey, run npm run canary:idescat. It builds the server, then checks search -> geos -> metadata -> bounded data against a known PMH table using the public MCP tool surface.

Open Data BCN Workflow

Use Open Data BCN for Barcelona city datasets such as street trees, equipment, mobility, facilities, and municipal services. For common city questions, start with bcn_recommend_resources; it returns likely resources, suggested tools, and example arguments. Use package search when the recommender is too narrow or the topic is not covered, then choose DataStore query, geospatial query, or download preview based on the resource metadata and the user's question.

{
  "query": "facilities in Gracia district",
  "task": "within",
  "place_kind": "district",
  "limit": 3
}

For open-ended discovery, search packages directly:

{
  "query": "arbrat viari",
  "limit": 5
}

Keep the returned package_id, then call bcn_get_package:

{
  "package_id": "27b3f8a7-e536-4eea-b025-ce094817b2bd"
}

Each resource includes resource_id, format, URL, and datastore_active.

2. Plan Or Execute A City Question

Use bcn_plan_query when the user asks a natural city question and you want an inspectable workflow:

{
  "query": "tree species on Carrer Consell de Cent",
  "limit": 10
}

The planner returns status, deterministic intent, recommended resources, optional place-resolution candidates, ordered steps, final_tool, final_arguments, and citation guidance. place_kind: "point" maps to resolver kinds ["landmark", "facility"]; street, neighborhood, and district pass through. Grouped prompts choose group_by deterministically: explicit input first, then neighborhood grouping for within-area questions, then the first recommended grouping field.

Use bcn_execute_city_query for the same input when a one-call bounded raw result is acceptable. It executes only when the plan is ready; otherwise it returns execution_status: "blocked" with the plan. For area plans, it copies selected_candidate.area_ref into within_place.{source_resource_id,row_id,geometry_field}. If no area_ref is available but a resolver bbox is available, it uses bbox with a caveat; if neither exists, the plan is blocked/unsupported.

Use bcn_answer_city_query when callers need a ready-to-display deterministic answer. It runs the same executor, then returns answer_text, answer_markdown, answer_type, compact summary, deduped warning caveats such as bbox fallback or scan caps, informational execution_notes such as SQL pushdown mode or bounded download scans, selected resource metadata, citation guidance, and the raw final_result. Blocked answers include normalized selection_options with labels, provenance, confidence, and resume_arguments; row summaries include labels and selected fields for display plus summary.rows[].source_row for client drill-down without re-parsing final_result. Row and nearest summaries also include summary.map_points[] when coordinates are available, with {label, lat, lon, distance_m?, source_row} for map rendering.

3. Inspect A Resource

Call bcn_get_resource_info before querying:

{
  "resource_id": "52696168-d8bc-4707-9a09-a21c6c2669f3"
}

If datastore_active is true, the response includes queryable fields.

4. Query Active DataStore Resources

bcn_query_resource always uses POST JSON. Filters are structured CKAN DataStore filters, not SQL text or URL fragments:

{
  "resource_id": "52696168-d8bc-4707-9a09-a21c6c2669f3",
  "fields": ["_id", "Districte", "Barri"],
  "filters": {
    "Districte": "Sant Martí"
  },
  "limit": 10
}

The response includes request_body with the logical replayable request, row counts, truncation flags, and provenance.

5. Resolve Named Places

Use bcn_resolve_place when the user gives a place name instead of coordinates. The resolver is source-bounded: it queries an explicit Open Data BCN DataStore registry, ranks matching rows locally, and returns candidate WGS84 points with matched fields and source provenance. The registry covers building-address street points, administrative district and neighborhood boundaries, municipal facilities, and parks/gardens. District and neighborhood candidates include bbox plus area_ref when BCN exposes WGS84 boundary geometry; pass area_ref to bcn_query_resource_geo.within_place for "in this district/neighborhood" questions.

{
  "query": "Sagrada Familia",
  "kinds": ["landmark"],
  "limit": 3
}

Street and area names use the same tool:

{
  "query": "Plaça Catalunya",
  "kinds": ["street"],
  "limit": 3
}

{
  "query": "Gracia",
  "kinds": ["district", "neighborhood"],
  "limit": 5
}

Use the best point candidate's lat and lon in bcn_query_resource_geo.near. For district and neighborhood candidates, prefer within_place when area_ref is present. Optional resolver bbox and kinds filters can narrow ambiguous names.

6. Query Resources Geospatially

Use bcn_query_resource_geo when the resource has WGS84 coordinate fields. It works across DataStore-active resources and safe BCN-hosted CSV/JSON downloads. DataStore resources with near, bbox, or within_place use generated datastore_search_sql internally so spatial narrowing happens upstream; callers still provide only structured inputs, never raw SQL. within_place first applies the resolved area's bbox upstream, then validates exact polygon containment locally. The tool infers common latitude/longitude pairs such as latitud / longitud, geo_epgs_4326_lat / geo_epgs_4326_lon, and geo_epgs_4326_y / geo_epgs_4326_x; if multiple pairs exist, pass lat_field and lon_field. It does not convert ETRS89 x/y fields.

Street or name matching uses contains:

{
  "resource_id": "23124fd5-521f-40f8-85b8-efb1e71c2ec8",
  "contains": {
    "espai_verd": "Carrer Consell de Cent"
  },
  "group_by": "cat_nom_catala",
  "fields": ["espai_verd", "adreca", "cat_nom_catala"],
  "limit": 10
}

Nearby queries use explicit coordinates:

{
  "resource_id": "d4803f9b-5f01-48d5-aeef-4ebbd76c5fd7",
  "near": {
    "lat": 41.4036,
    "lon": 2.1744,
    "radius_m": 750
  },
  "fields": ["name", "addresses_road_name", "addresses_neighborhood_name"],
  "limit": 10
}

Area queries use area_ref from bcn_resolve_place:

{
  "resource_id": "d4803f9b-5f01-48d5-aeef-4ebbd76c5fd7",
  "within_place": {
    "source_resource_id": "576bc645-9481-4bc4-b8bf-f5972c20df3f",
    "row_id": 6,
    "geometry_field": "geometria_wgs84"
  },
  "fields": ["name", "addresses_neighborhood_name", "addresses_district_name"],
  "group_by": "addresses_neighborhood_name",
  "limit": 10
}

The response includes strategy, datastore_mode (sql or scan) for DataStore resources, coordinate_fields, _geo coordinates with optional distance_m, scan counts, match counts, truncation flags, upstream_total for fully upstream-filtered DataStore resources, and groups when group_by is provided. When a DataStore SQL query still needs local within_place polygon filtering, upstream_bbox_total reports the bbox-matching upstream count before exact polygon containment. When local contains filtering is applied after SQL pushdown, upstream_prefilter_total reports the upstream count before the local text filter. When within_place and contains are combined, both fields are present and report the same pre-local-filter count (i.e., bbox-matching rows that also satisfy the SQL WHERE clause). The logical_request_body.sql in provenance reflects the caller's logical query (using their limit/offset); the runtime issues paginated upstream calls behind it whenever local post-filtering is needed, so replaying the logical SQL verbatim returns bbox-matching rows, not the post-filtered slice. Group rows include count, sample, and for near queries min_distance_m plus sample_nearest.

DataStore near, bbox, and within_place queries push spatial predicates into CKAN SQL, while DataStore calls without spatial inputs and download resources still scan locally. By default, BCN geo CSV scans read the full download so late rows are not missed. If CATALUNYA_MCP_BCN_GEO_SCAN_MAX_ROWS is set and truncation_reason is scan_cap, additional matches may exist beyond the scanned rows; narrow bbox, contains, or filters, or unset the cap for trusted local runs. Download JSON resources are accepted only when small enough to parse as complete documents; larger JSON resources should use a DataStore or CSV sibling.

7. Preview Inactive CSV/JSON Resources

If datastore_active is false, use bcn_preview_resource for a bounded sample:

{
  "resource_id": "23124fd5-521f-40f8-85b8-efb1e71c2ec8",
  "limit": 5
}

Preview is intentionally not an export tool. It only follows HTTPS URLs hosted by opendata-ajuntament.barcelona.cat, validates every redirect, reads at most CATALUNYA_MCP_BCN_UPSTREAM_READ_BYTES + 1, and parses CSV/JSON into capped rows.

Query Safety

The server is deliberately defensive:

It is read-only.
It validates Socrata source IDs before calling upstream APIs.
It caps returned rows with CATALUNYA_MCP_MAX_RESULTS.
It caps response size with CATALUNYA_MCP_RESPONSE_MAX_BYTES.
It applies request timeouts with CATALUNYA_MCP_REQUEST_TIMEOUT_MS.
It preserves upstream error details when they help the model fix a query.
It maps IDESCAT cell-limit errors to narrow_filters with the original JSON-stat error in source_error.
It restricts Open Data BCN previews to allowlisted HTTPS BCN download hosts and caps upstream preview bytes.
It reuses the same BCN download allowlist for geospatial CSV/JSON scans. Optional BCN geo scan byte/row caps can be set for constrained deployments.

If Socrata rejects a query, inspect error.message. For example, query.soql.no-such-column means the query used an invalid field. Return to socrata_describe_dataset, choose a valid field_name, and retry with a corrected clause.

Configuration

The server reads configuration from environment variables supplied by the shell or MCP client. It does not auto-load .env files; .env.example is provided as a copyable reference.

Variable	Default	Notes
`NODE_ENV`	`development`	One of `development`, `test`, or `production`.
`LOG_LEVEL`	`info`	One of `trace`, `debug`, `info`, `warn`, `error`, or `silent`. Logs go to stderr so stdio transport remains clean.
`CATALUNYA_MCP_TRANSPORT`	`stdio`	Only `stdio` is supported in the current implementation.
`CATALUNYA_MCP_MAX_RESULTS`	`100`	Maximum rows/results per tool call. Hard limit: `1000`.
`CATALUNYA_MCP_REQUEST_TIMEOUT_MS`	`30000`	Upstream request timeout. Allowed range: `100` to `120000`.
`CATALUNYA_MCP_RESPONSE_MAX_BYTES`	`262144`	Maximum upstream response body size. Allowed range: `65536` to `1048576`.
`CATALUNYA_MCP_IDESCAT_UPSTREAM_READ_BYTES`	`8388608`	Maximum IDESCAT upstream success body to read before flattening/capping. Allowed range: `65536` to `33554432`.
`CATALUNYA_MCP_BCN_UPSTREAM_READ_BYTES`	`2097152`	Maximum Open Data BCN download preview body to read before parsing/capping. Allowed range: `65536` to `16777216`.
`CATALUNYA_MCP_BCN_GEO_SCAN_MAX_ROWS`	unset	Optional maximum Open Data BCN rows to scan for geospatial helper calls. Unset or `0` means unlimited.
`CATALUNYA_MCP_BCN_GEO_SCAN_BYTES`	unset	Optional maximum Open Data BCN CSV/JSON download body to read for one geospatial helper call. Unset or `0` means unlimited.
`SOCRATA_APP_TOKEN`	unset	Optional Socrata app token for better rate-limit stability.

Example client configuration with environment overrides:

{
  "mcpServers": {
    "catalunya-opendata": {
      "command": "node",
      "args": ["/absolute/path/to/catalunya-opendata-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "warn",
        "CATALUNYA_MCP_MAX_RESULTS": "250",
        "SOCRATA_APP_TOKEN": "your-token"
      }
    }
  }
}

Development

Command	What it does
`npm run dev`	Starts the stdio server with `tsx watch`.
`npm run build`	Compiles TypeScript to `dist/`.
`npm start`	Runs the built server.
`npm run typecheck`	Type-checks source and tests.
`npm test`	Runs the Vitest suite.
`npm run smoke`	Builds the server and checks core tool/prompt/resource registration over stdio, then calls `ping`.
`npm run doctor`	Builds the server and checks runtime/configuration, build output, package budget, stdio smoke, and upstream reachability.
`npm run canary:socrata`	Builds the server and runs the live Socrata search -> describe -> query canary.
`npm run canary:idescat`	Builds the server and runs the live IDESCAT search -> geos -> metadata -> data canary.
`npm run canary:bcn-registry`	Builds the server and checks curated BCN resource recommendations against live package/resource metadata.
`npm run canary:live`	Builds once, runs all dedicated live connector canaries, then runs the live MCP canary evaluation.
`npm run eval:canary`	Builds the server and runs the live binary MCP evaluation canary.
`npm run eval:stress`	Builds the server and runs the full live binary MCP evaluation suite.
`npm run eval:replay:canary`	Replays the canary evaluation from the committed MCP cassette.
`npm run eval:replay:stress`	Replays the full evaluation suite from the committed MCP cassette.
`npm run package:size`	Checks packed/unpacked package size and total generated IDESCAT index size.
`npm run inspect`	Builds the server and opens the MCP Inspector against `dist/index.js`.
`npm run refresh:idescat`	Crawl IDESCAT Tables v2 and regenerate the committed search index.
`npm run lint`	Runs Biome checks.
`npm run format`	Formats the repository with Biome.
`npm run check`	Runs typecheck, lint, tests, smoke, and package size checks.
`npm run release:check`	Runs the local check gate, then replays the full stress MCP evaluation cassette.
`npm run release:verify`	Runs `release:check`, then verifies clean/synced git state, version notes, packed files, tag-to-HEAD alignment, green CI, and npm publish posture.

Evaluations

The repository includes live MCP evaluations for checking how well the server performs as an actual MCP adapter, not just as local TypeScript modules. The evaluator builds the project, starts node dist/index.js over stdio, calls the public MCP surface, and grades each tool, prompt, and resource response with a deterministic pass/fail assertion.

Use replay mode for deterministic local or CI checks that should not depend on live upstream availability:

npm run eval:replay:canary
npm run eval:replay:stress

Replay mode reads committed cassettes from tests/fixtures/evals/. It exercises the same evaluation logic and report schema, but returns previously captured MCP responses instead of calling Socrata or IDESCAT.

Use live mode while checking current upstream behavior:

npm run canary:live
npm run eval:canary
npm run eval:stress

The GitHub Actions Live Canary workflow is manual-only. It installs dependencies, builds once, optionally runs the dedicated Socrata, IDESCAT, and BCN connector canaries, then runs the selected canary or stress MCP evaluation profile and uploads the JSON report artifact.

Refresh cassettes after intentionally changing adapter behavior or accepting upstream drift:

npm run eval:record:canary
npm run eval:record:stress

The stress profile currently runs 152 live cases:

Connector	Cases
MCP surface	1
Socrata	53
Open Data BCN	27
IDESCAT	71

The cases cover discovery, metadata, bounded data queries, safe BCN CSV preview, BCN resource recommendations, BCN place resolution for landmarks, streets, neighborhoods, and districts, BCN city-query planning/execution/answering, BCN answer composition for grouped, nearest, blocked, and empty answers, BCN area-aware geospatial queries, prompts, metadata resources, pagination, invalid inputs, upstream errors, local cap behavior, low-response-cap degradation, and the IDESCAT long-filter regression. In particular, the IDESCAT regression verifies long multi-value filters stay in a canonical GET URL, return request_method: "GET", omit request body params, and preserve the expected selected cell count.

Every run writes a machine-readable JSON report under tmp/, for example tmp/mcp-eval-stress-<timestamp>.json. The report includes each case id, inputs, binary score, failure reason, sub-assertions with expected and actual values, duration, compact result summary, connector totals, and expected-count checks. A run fails if any case fails or if the expected MCP/Socrata/IDESCAT case counts drift.

Live evals are intentionally separate from npm run check because they call Generalitat and IDESCAT services. If an upstream service is down or rate-limited, a live eval can fail even when local unit tests and replay evals are healthy. For more detail on the evaluation design, cassette modes, and report format, see docs/evaluations.md.

Client-facing golden answer examples for grouped, nearest, blocked, empty, and caveat-bearing BCN answers live in docs/golden-answers.md. The machine-readable answer contract lives in docs/contracts/bcn-answer-city-query.schema.json.

Release Checklist

Before opening or merging routine changes, run npm run check. This stays local and does not include live upstream canaries.

For release readiness, run npm run release:check. This includes npm run check plus npm run eval:replay:stress, so it covers typecheck, lint, unit tests, smoke output, package size budget, and the committed protocol-level stress cassette.

Before publishing a GitHub release, run npm run release:verify from the commit being released after its v<package.version> tag has been pushed. It re-runs the release gate, then checks that the worktree is clean, the branch is synced, package.json, package-lock.json, and docs/release-notes.md agree on the version, the packed package only contains dist/, README.md, LICENSE, and package.json, local and remote tags point at HEAD, GitHub Actions CI is green for HEAD, and the package's private/public npm posture is explicit. Use node scripts/release-verify.mjs --require-release after creating the GitHub release when you want a post-release confirmation.

Before publishing a package, run npm pack --dry-run, confirm the tarball includes only dist/, README.md, LICENSE, and package.json, and confirm dist/index.js is executable with test -x dist/index.js. The package budget remains enforced by npm run package:size; current limits are 512 KiB packed, 8 MiB unpacked, 5 MiB source IDESCAT index, and 7 MiB built IDESCAT index.

For adapter changes that may need fresh live evidence, optionally run npm run canary:live, npm run eval:stress, and, when accepting upstream drift or intentional adapter changes, npm run eval:record:stress. These commands exercise the public MCP surface against live Generalitat/IDESCAT/Open Data BCN services, so they are intentionally manual and may fail when an upstream service is unavailable. The GitHub Actions Live Canary workflow can also be started manually with either the canary or stress evaluation profile. The evaluation harness writes a JSON report with binary case scores and connector-level summaries; see docs/evaluations.md. User-facing release notes live in docs/release-notes.md.

Operational release and upstream-incident guidance lives in docs/operations.md. Install-from-tarball smoke guidance lives in docs/install-smoke.md.

Project Notes

The current implementation is intentionally small: one transport and three source adapters (Socrata catalog/query, IDESCAT Tables v2 browse/metadata/data, and Open Data BCN catalog/query/place/geo workflows). The IDESCAT search index ships as committed generated source; refresh it manually with npm run refresh:idescat when the upstream catalog changes. Broader architecture notes live in specs.md, but the README documents what the repository does today.

License

MIT. See LICENSE.

Available Tools

22 tools

bcn_answer_city_querybcn.answer_city_queryC

Execute a safe bounded Open Data BCN city-question plan and compose a deterministic caller-ready answer. Returns answer_text, answer_markdown, blocked selection_options, map-ready summary points, caveats, execution_notes, selected resource metadata, citation guidance, and the raw final_result.

ParametersJSON Schema

Name	Required	Description
`q`	No
`sort`	No
`task`	No
`limit`	No	Rows to return. Server maximum: 100.
`query`	Yes
`fields`	No
`offset`	No
`filters`	No
`group_by`	No
`radius_m`	No
`place_kind`	No
`place_query`	No
`resource_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

C2.4/5.0

Behavior2/5

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

No annotations are provided, so the description must carry full burden. It states 'safe bounded' but does not explain what that means in practice, nor does it disclose side effects, auth requirements, rate limits, or any behavioral traits. The output fields listed are not behavioral context.

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

Conciseness3/5

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

The description is a single sentence and front-loaded with the main action, but it is dense and lists many output fields. Some cutting could improve readability without losing essential information.

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

Completeness2/5

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

Given the tool's complexity (13 parameters, nested objects, no annotations), the description is incomplete. It lacks parameter guidance, usage context, and behavioral details. The presence of an output schema does not compensate for the lack of input parameter explanations.

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

Parameters1/5

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

Schema description coverage is only 8% (only 'limit' has a description). The tool description does not explain any parameters, leaving 12 parameters largely undocumented. The description adds no meaning beyond the schema's minimal info.

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

Purpose4/5

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

The description clearly states the tool executes a city-question plan and composes an answer, listing many return fields. It identifies the specific resource and action, but does not differentiate from sibling tools like 'bcn_execute_city_query' or 'bcn_plan_query', missing an opportunity to clarify its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives, nor any conditions or prerequisites. The description does not mention when not to use it or what distinguishes it from similar tools.

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

bcn_execute_city_querybcn.execute_city_queryC

Execute a safe bounded Open Data BCN city-question plan end-to-end. Blocks instead of guessing when the planner needs a resource or place selection.

ParametersJSON Schema

Name	Required	Description
`q`	No
`sort`	No
`task`	No
`limit`	No	Rows to return. Server maximum: 100.
`query`	Yes
`fields`	No
`offset`	No
`filters`	No
`group_by`	No
`radius_m`	No
`place_kind`	No
`place_query`	No
`resource_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

C2.6/5.0

Behavior2/5

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

Without annotations, the description carries the full burden. It claims the tool is 'safe bounded' and 'blocks instead of guessing,' but fails to explain side effects, authorization needs, rate limits, or error handling. The behavior remains opaque.

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?

The description is extremely concise (two sentences) and front-loads the main action. Every word serves a purpose with no redundancy.

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

Completeness2/5

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

Given high complexity (13 parameters, nested objects, output schema), the description is severely incomplete. It does not explain what a 'city-question plan' is, how to construct one, or how parameters relate. The output schema exists but goes unmentioned.

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

Parameters2/5

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

Schema description coverage is only 8%, yet the description adds no parameter details. It does not explain what parameters like place_kind, resource_id, or group_by represent, leaving the agent to guess despite the complexity.

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

Purpose3/5

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

The description states it executes a 'city-question plan' and mentions safe/bounded behavior, but does not clearly differentiate from siblings like bcn_plan_query or bcn_answer_city_query. The term 'blocks instead of guessing' is vague and doesn't clarify the tool's specific role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus siblings. The phrase 'blocks instead of guessing' implies a behavior but offers no decision-making criteria or mention of alternatives.

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

bcn_get_packagebcn.get_packageB

Fetch one Open Data BCN package, including resource IDs, formats, DataStore activity, package license, and provenance.

ParametersJSON Schema

Name	Required	Description	Default
`package_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

B3/5.0

Behavior2/5

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

With no annotations, description must cover behavioral traits. It does not mention side effects, authentication, rate limits, or error handling. Only states what is included in the response.

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?

Single sentence, 20 words, front-loaded with action and scope, zero waste.

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?

Output schema exists, so return values need no explanation. However, given no annotations and no description for the sole parameter, completeness is adequate but not thorough.

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

Parameters1/5

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

Schema coverage is 0%, yet description adds no meaning to the only parameter (package_id). No format, example, or purpose beyond schema definition.

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?

Description clearly specifies verb 'fetch', resource 'Open Data BCN package', and lists included details (resource IDs, formats, etc.), distinguishing it from siblings like bcn_search_packages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives, no prerequisites or exclusions. Implies use for single package fetch but does not clarify when not to use.

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

bcn_get_resource_infobcn.get_resource_infoA

Inspect one Open Data BCN resource. Active DataStore resources include queryable fields; inactive resources should use bcn_preview_resource.

ParametersJSON Schema

Name	Required	Description	Default
`resource_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A3.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It does not explicitly state if the tool is read-only, non-destructive, or any safety constraints. The name implies inspection, but behavioral traits like side effects or auth needs are not disclosed.

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 wasted words. Purpose is front-loaded, and every sentence adds value. Highly concise.

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

Completeness4/5

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

Given the tool's simplicity (one parameter, output schema exists), the description covers the key distinction between active/inactive resources. It is nearly complete; only minor behavioral transparency is missing.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It does not explain what 'resource_id' is or how to obtain it. The only parameter is not described beyond the schema's type constraint.

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?

The description clearly states 'Inspect one Open Data BCN resource' with a specific verb and resource. It distinguishes from siblings by noting that active DataStore resources include queryable fields, and inactive resources should use bcn_preview_resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicitly tells when to use this tool (inspect a resource) and when to use an alternative (bcn_preview_resource for inactive resources). Provides clear context about active vs inactive resources.

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

bcn_plan_querybcn.plan_queryA

Plan a natural-language Barcelona city question into an explainable Open Data BCN workflow. Returns recommended resources, optional source-bounded place resolution, final tool arguments, and citation guidance without running the final data query.

ParametersJSON Schema

Name	Required	Description
`q`	No
`sort`	No
`task`	No
`limit`	No	Rows to return. Server maximum: 100.
`query`	Yes
`fields`	No
`offset`	No
`filters`	No
`group_by`	No
`radius_m`	No
`place_kind`	No
`place_query`	No
`resource_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A3.6/5.0

Behavior4/5

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

No annotations are provided, so the description carries full burden. It clearly states the tool returns a plan without side effects, listing key output components. It lacks details on authorization or rate limits, which is acceptable for a planning tool.

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

Conciseness4/5

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

The single-sentence description is concise and front-loads the purpose. While it could be more structured with bullet points, it avoids unnecessary words.

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?

The description mentions key outputs and has an output schema, but given the complexity (13 parameters, nested objects), it omits details about the output structure and parameter use, leaving the agent with incomplete context.

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

Parameters2/5

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

Schema description coverage is only 8%, and the description does not explain any of the 13 parameters beyond implying 'query' is the natural-language input. This is a significant gap given the number of parameters.

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

Purpose4/5

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

The description clearly states the tool's function: planning a natural-language Barcelona city question into an explainable workflow, with a list of return items. It distinguishes from sibling tools like bcn_execute_city_query by noting it does not run the final query, but lacks explicit differentiation from bcn_recommend_resources or bcn_resolve_place.

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?

The description explicitly notes the tool is for planning and 'without running the final data query,' guiding when to use it versus execution tools. However, it does not provide exclusions or mention alternatives like bcn_query_resource for direct queries.

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

bcn_preview_resourcebcn.preview_resourceA

Fetch a safe, bounded CSV or JSON preview for an Open Data BCN non-DataStore resource. Only HTTPS BCN-hosted download URLs and validated redirects are followed.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Rows to return. Server maximum: 100.
`resource_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It discloses that the tool only follows HTTPS BCN-hosted URLs and validated redirects, providing important safety and behavior cues beyond the basic fetch action.

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 concise sentences, front-loaded with the core purpose, no wasted words.

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

Completeness4/5

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

Given the presence of an output schema and the tool's simplicity, the description covers the essential context (safe, bounded, non-DataStore). It could mention error behavior or format details, but is largely complete.

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

Parameters2/5

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

Schema coverage is 50% (only 'limit' has description). The description does not add meaning for 'resource_id', which is undocumented. It only mentions 'CSV or JSON preview' vaguely. This is insufficient compensation for the missing schema description.

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?

The description clearly states the action ('Fetch'), the resource ('preview for an Open Data BCN non-DataStore resource'), and the boundaries (CSV or JSON). It distinguishes from sibling tools like bcn_query_resource and bcn_get_resource_info by specifying 'non-DataStore'.

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?

The description specifies that the tool is for non-DataStore resources, providing clear context. However, it does not explicitly mention alternatives or when not to use it, which would move it to a 5.

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

bcn_query_resourcebcn.query_resourceA

Query rows from an active Open Data BCN CKAN DataStore resource. Call bcn_get_resource_info first when possible and use returned field IDs. Pass filters as a JSON object, not raw SQL or URL query fragments. This always uses POST JSON to datastore_search and returns a bounded page with explicit truncation. If the resource is not DataStore-active, use bcn_preview_resource for a bounded CSV/JSON download preview.

ParametersJSON Schema

Name	Required	Description
`q`	No
`sort`	No
`limit`	No	Rows to return. Server maximum: 100.
`fields`	No
`offset`	No
`filters`	No
`resource_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

Discloses use of POST JSON to datastore_search, returns bounded page with truncation. No annotations provided, so description carries burden; lacks details on rate limits or authentication but sufficient for typical use.

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?

Five sentences, no fluff, front-loaded purpose, then guidelines, then technical details.

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

Completeness4/5

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

Output schema exists, so return values not needed. Covers main behavior, pagination mentions truncation but lacks full pagination details. Overall adequate.

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

Parameters3/5

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

Schema coverage is low (14%), but description adds context: filters must be JSON, fields should come from bcn_get_resource_info. Does not detail all parameters like q, sort, offset.

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?

The description clearly states it queries rows from an active Open Data BCN CKAN DataStore resource, distinguishing it from siblings like bcn_preview_resource for non-active resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicit guidance: call bcn_get_resource_info first, use JSON filters, avoid raw SQL, prefer POST, and use bcn_preview_resource if resource is not DataStore-active.

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

bcn_query_resource_geobcn.query_resource_geoA

Run a bounded geospatial query over an Open Data BCN resource with WGS84 latitude/longitude columns. Works for DataStore-active resources and safe BCN-hosted CSV/JSON downloads; active near/bbox calls use generated CKAN SQL internally. Use near for distance queries, bbox for rectangular areas, within_place for district/neighborhood polygons returned by bcn_resolve_place.area_ref, contains for street/name text filters, and group_by for counts such as species by street. Coordinate fields are inferred from common BCN names such as latitud/longitud, geo_epgs_4326_lat/geo_epgs_4326_lon, and geo_epgs_4326_y/geo_epgs_4326_x; pass lat_field/lon_field when ambiguous.

ParametersJSON Schema

Name	Required	Description
`bbox`	No
`near`	No
`limit`	No	Rows to return. Server maximum: 100.
`fields`	No
`offset`	No
`filters`	No
`contains`	No
`group_by`	No
`lat_field`	No
`lon_field`	No
`group_limit`	No
`resource_id`	Yes
`within_place`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

No annotations supplied, so description must disclose behavior. It mentions that active near/bbox calls use generated CKAN SQL internally and explains coordinate field inference. It does not explicitly state read-only nature or error behavior, but the geospatial focus and 'safe' mention imply non-destructive behavior.

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?

A single paragraph of five sentences, each adding distinct value: purpose, data sources, query types, coordinate inference, and fallback for ambiguous fields. No fluff, front-loaded.

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

Completeness4/5

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

Given 13 parameters, nested objects, and an output schema, the description covers the core geospatial functionality and most important parameters. It lacks details on filters and pagination, but those are standard. Overall adequate for initial selection.

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 description coverage is only 8%, so the description compensates by explaining the main geospatial parameters (near, bbox, within_place, contains, group_by, lat_field, lon_field). However, it does not explain filters, offset, or fields, leaving some gap for complex filters.

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?

The description clearly states the tool's purpose: running bounded geospatial queries over Open Data BCN resources with WGS84 coordinates. It distinguishes from sibling tools like bcn_query_resource by specifying geospatial capabilities and listing query types (near, bbox, within_place, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Provides explicit when-to-use guidance: 'Use near for distance queries, bbox for rectangular areas, within_place for district/neighborhood polygons...'. It also clarifies that it works for DataStore-active resources and safe CSV/JSON downloads, setting prerequisites.

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

bcn_recommend_resourcesbcn.recommend_resourcesA

Recommend high-value Open Data BCN resources for a natural-language city question. Use this before package search when the user asks broad questions such as trees on a street, facilities near a place, parks in an area, or district/neighborhood boundaries. The recommender is deterministic and source-bounded; follow up with bcn_get_resource_info, bcn_resolve_place, or bcn_query_resource_geo.

ParametersJSON Schema

Name	Required	Description
`task`	No
`limit`	No	Rows to return. Server maximum: 100.
`query`	Yes
`place_kind`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It discloses the tool is deterministic, source-bounded, and intended as a recommender. It does not mention rate limits or failure modes, but these are less critical. The description implies read-only behavior, which is adequate.

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 efficiently convey purpose, usage context, and parameter hints. No wasted words, front-loaded with the main action. Examples are concrete and helpful.

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

Completeness4/5

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

Given the tool has an output schema (though not shown), the description need not detail return values. It covers usage sequence, parameter intent, and ties to sibling tools. Slightly incomplete: could specify what 'high-value' means or the format of recommendations, but overall sufficient for an AI agent.

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

Parameters3/5

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

Schema description coverage is 25% (only limit parameter described). The description adds 'natural-language city question' for the query parameter, but provides no added meaning for task or place_kind, which are enums without descriptions. Baseline 3 because description partially compensates for low schema coverage.

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?

The description clearly states it recommends high-value Open Data BCN resources for natural-language city questions. It differentiates from sibling tools like bcn_search_packages by specifying it should be used 'before package search' for broad questions, and mentions follow-up tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicitly tells when to use (before package search for broad questions like 'trees on a street', 'facilities near a place') and suggests follow-up tools (bcn_get_resource_info, bcn_resolve_place, bcn_query_resource_geo). Also notes the recommender is deterministic and source-bounded.

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

bcn_resolve_placebcn.resolve_placeA

Resolve a Barcelona place name to candidate WGS84 coordinates using only source-bounded Open Data BCN DataStore resources. Use this before bcn_query_resource_geo when the user gives a named place instead of lat/lon. Supports optional bbox and kind filters for facilities, landmarks, streets, neighborhoods, and districts.

ParametersJSON Schema

Name	Required	Description
`bbox`	No
`kinds`	No
`limit`	No	Rows to return. Server maximum: 100.
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It states it returns candidate coordinates using source-bounded resources, implying geocoding with multiple possibilities. Lacks details on error handling, no-match behavior, or rate limits.

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, no filler, front-loaded with purpose. Every sentence adds necessary context without redundancy.

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

Completeness4/5

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

Has output schema to document returns. Covers core geocoding function, filters, and usage in relation to sibling. Could mention default behavior or handling of ambiguous queries, but overall adequate.

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

Parameters3/5

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

Schema description coverage is 25% (only limit described). Description adds meaning for bbox and kinds by listing filter types (facilities, landmarks, etc.) but does not detail all schema properties like bbox structure. Partially compensates for low coverage.

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?

The description clearly states the tool resolves Barcelona place names to WGS84 coordinates using specific Open Data BCN resources. It distinguishes from sibling bcn_query_resource_geo by noting it is for named places instead of lat/lon.

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 instructs use before bcn_query_resource_geo when user provides a named place. Mentions optional bbox and kind filters, but does not explicitly state when not to use or provide alternative sibling references beyond the one.

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

bcn_search_packagesbcn.search_packagesC

Discover Open Data BCN CKAN packages for Barcelona city datasets such as street trees, facilities, mobility, equipment, and services.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes
`offset`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

C2.4/5.0

Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It only offers a high-level purpose and examples, with no information on authentication, rate limits, pagination, result format, or any side effects. This is insufficient for an AI agent to understand the tool's behavior.

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

Conciseness3/5

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

The description is extremely concise (one sentence). While brevity is valued, it sacrifices necessary detail. It could be restructured to include parameter hints or usage context without significant lengthening.

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

Completeness2/5

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

Given the presence of an output schema (context indicates it exists), the description does not need to detail return values. However, the description is too sparse: it lacks parameter semantics, usage guidance, and behavioral context. The tool has several parameters and many siblings, so completeness is low.

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

Parameters1/5

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

Schema description coverage is 0%, meaning the schema itself provides no parameter descriptions. The description adds no information about the three parameters (query, limit, offset). It does not explain that 'query' is a search string or that 'limit' and 'offset' paginate results. This is a critical gap.

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

Purpose4/5

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

The description clearly identifies the tool's purpose: to discover or search for CKAN packages on Open Data BCN related to Barcelona city datasets. It provides examples of dataset types, which helps distinguish it from sibling tools like bcn_get_package (which retrieves a specific package). However, it could be more explicit about the search action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. With many sibling tools for querying, previewing, and searching, the description should indicate that this is the primary search tool for discovering packages, while others are for specific operations. Missing context on when to use search vs other tools.

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

idescat_get_table_dataidescat.get_table_dataA

Fetch a bounded, flattened IDESCAT data extract only after idescat_list_table_geos and idescat_get_table_metadata. Every request requires statistics_id, node_id, table_id, and geo_id. Use metadata dimension/category IDs exactly in filters, and use last for recent periods. This is not an exhaustive export tool; if IDESCAT returns narrow_filters, call metadata and retry with filters or last.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`last`	No
`limit`	No
`geo_id`	Yes
`filters`	No
`node_id`	Yes
`table_id`	Yes
`statistics_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.1/5.0

Behavior3/5

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

No annotations exist, so description must compensate. It mentions boundedness, flatness, non-exhaustive nature, and retry logic, but does not describe potential errors, side effects, or prerequisites being met.

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?

Three sentences front-load the main action and prerequisite, with no redundant information.

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?

Output schema exists, so return values are covered. However, given 8 parameters and no schema descriptions, the description omits details on 'lang', 'limit', and error handling, making it somewhat incomplete.

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

Parameters3/5

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

With 0% schema coverage, description adds meaning for required parameters and 'last'/'filters', but does not explain 'lang', 'limit', or the structure of the 'filters' object, leaving gaps.

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?

The description clearly states the tool fetches a bounded, flattened data extract and specifies it must be used after two sibling tools, distinguishing it from listing/metadata tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicitly says to use only after idescat_list_table_geos and idescat_get_table_metadata, and provides instructions for using filters, 'last', and retry logic when narrow_filters is returned.

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

idescat_get_table_metadataidescat.get_table_metadataA

Inspect an IDESCAT table after selecting geo_id with idescat_list_table_geos. Optionally pass place_query with the original user place phrase, such as Maresme or renda Girona, to receive filter_guidance. Use returned dimension IDs, category IDs, and filter_guidance.recommended_data_call exactly in idescat_get_table_data filters; use this tool or its metadata resource for citations.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`geo_id`	Yes
`node_id`	Yes
`table_id`	Yes
`place_query`	No
`statistics_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It reveals read-only inspection nature, explains optional place_query triggers filter_guidance, and describes output fields (dimension IDs, category IDs, recommended_data_call). Lacks detail on error conditions or restrictions, but sufficiently transparent for a metadata inspection tool.

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?

Three sentences: first states purpose and prerequisite, second covers optional parameter, third explains downstream use. No redundant words, information is front-loaded. Each sentence contributes distinct value.

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

Completeness4/5

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

Given the tool's role in a pipeline (6 params, 4 required, no annotations), the description covers key aspects: prerequisite, optional feature, and how to use results. It does not detail all parameters, but the output schema is available and the tool's purpose is clear. Minor gaps remain for full parameter documentation.

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

Parameters3/5

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

Schema_description_coverage is 0%, so description must compensate. It explains geo_id (through prerequisite context) and place_query (explicitly with examples). Other parameters (lang, node_id, table_id, statistics_id) are not described, though their roles can be inferred from tool name and typical use. Adds some meaning but not full semantics.

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?

Description clearly states 'Inspect an IDESCAT table' with specific verb and resource, and distinguishes itself by referencing prerequisite 'idescat_list_table_geos' and downstream tool 'idescat_get_table_data'. It also mentions optional usage for filter_guidance.

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 states prerequisite (after selecting geo_id with idescat_list_table_geos) and downstream integration (use returned IDs in idescat_get_table_data). Provides context for when to use, but does not explicitly state when not to use or list alternatives beyond the implicit differentiation from sibling tools.

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

idescat_list_nodesidescat.list_nodesA

Browse nodes under an IDESCAT statistic. Use a statistics_id from idescat_list_statistics, then call idescat_list_tables with the returned node_id.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`limit`	No
`offset`	No
`statistics_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only says 'browse,' implying a read-only operation, but does not specify whether it requires authentication, is destructive, or has rate limits. The presence of limit/offset hints at pagination but is not explicitly explained in the description.

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?

The description is extremely concise with two sentences. It front-loads the purpose and immediately provides the essential workflow. No unnecessary words or repetition.

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 tool with 4 parameters (including pagination) and an output schema, the description covers the basic purpose and workflow but omits details on pagination behavior, language options, and output structure (though output schema exists). It is adequate for a simple browse tool but lacks completeness for a full understanding.

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

Parameters2/5

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

Schema description coverage is 0%, so the description should explain parameters. Only statistics_id is mentioned ('Use a statistics_id...'). The other parameters (lang, limit, offset) are not described at all, leaving the agent to infer their meaning from the schema alone. This is insufficient given the lack of schema descriptions.

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?

The description clearly states the tool's purpose: 'Browse nodes under an IDESCAT statistic.' It specifies the resource (nodes) and verb (browse). It also provides a workflow hint linking to sibling tools (idescat_list_statistics and idescat_list_tables), distinguishing this tool from those that list statistics or tables.

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?

The description gives explicit usage context: 'Use a statistics_id from idescat_list_statistics, then call idescat_list_tables with the returned node_id.' This clearly guides the agent on prerequisites and subsequent steps. It doesn't include exclusions or when-not-to-use, but the flow is well-defined.

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

idescat_list_statisticsidescat.list_statisticsA

Browse fallback when idescat_search_tables is too broad or empty. Start here, then call idescat_list_nodes with a returned statistics_id.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`limit`	No
`offset`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A3.5/5.0

Behavior2/5

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

No annotations provided, and the description does not disclose any behavioral traits such as side effects, rate limits, or auth requirements. It only states the purpose, failing to add transparency beyond that.

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, front-loaded with key purpose and usage, no extraneous information.

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

Completeness2/5

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

Despite having an output schema, the description lacks parameter explanations and does not cover the full context needed to use the tool independently. It only covers the high-level workflow.

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

Parameters1/5

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

Schema description coverage is 0% and the description does not explain any of the three parameters (lang, limit, offset). Agent gets no guidance on their meaning or effect beyond the schema's type/enum definitions.

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?

Clearly states 'Browse fallback when idescat_search_tables is too broad or empty', specifying the action (browse) and resource (statistics), and distinguishes from sibling tools by positioning it as a fallback and part of a workflow with idescat_list_nodes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

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

Explicitly says when to use ('when idescat_search_tables is too broad or empty'), and what to do after ('call idescat_list_nodes with a returned statistics_id'), providing a clear usage flow and alternatives.

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

idescat_list_table_geosidescat.list_table_geosB

Required bridge from table discovery to metadata/data. Choose a returned geo_id, then call idescat_get_table_metadata before idescat_get_table_data.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`limit`	No
`offset`	No
`node_id`	Yes
`table_id`	Yes
`statistics_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

B3/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It does not disclose whether the tool is read-only, requires authentication, has rate limits, or pagination behavior. The only hint is 'list' implying read, but that is insufficient.

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

Conciseness4/5

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

Single sentence, concise and front-loaded with purpose. However, it sacrifices critical details for brevity, making it less useful than it could be.

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

Completeness2/5

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

Given the absence of parameter descriptions in schema and no annotations, the description should compensate. It fails to explain required inputs or output structure (though output schema exists). The tool has 6 parameters, 3 required, yet the description ignores them entirely.

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

Parameters1/5

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

Schema coverage is 0% (no descriptions in schema), and the description adds no meaning to any of the 6 parameters (statistics_id, node_id, table_id, lang, limit, offset). Agent has no clue what each parameter represents or how to use them.

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

Purpose4/5

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

The description states it's a 'bridge from table discovery to metadata/data' and instructs to 'choose a returned geo_id', clearly indicating the tool lists geographic variants for a table. It distinguishes its role from sibling data/metadata tools.

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 prescribes the workflow order: use this tool, then call idescat_get_table_metadata before idescat_get_table_data. However, it does not mention when not to use it or provide alternatives.

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

idescat_list_tablesidescat.list_tablesB

Browse tables within an IDESCAT statistic node. Use returned statistics_id, node_id, and table_id with idescat_list_table_geos before metadata or data.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`limit`	No
`offset`	No
`node_id`	Yes
`statistics_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

B3.2/5.0

Behavior2/5

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

No annotations are provided, so the description must fully disclose behavioral traits. It does not mention pagination (though limit/offset parameters exist), error conditions, rate limits, or authentication requirements. The description only indicates a read-like operation but lacks sufficient behavioral detail.

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?

The description is extremely concise: two sentences with no redundant information. The first sentence states the purpose, and the second provides critical usage context. Every word earns its place.

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?

While an output schema is present, the description fails to cover key aspects like pagination behavior (despite limit/offset parameters) and error handling. Given the absence of annotations and parameter descriptions, the description is not complete enough for an agent to use the tool effectively without additional context.

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

Parameters1/5

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

The input schema has 5 parameters with 0% schema description coverage, but the tool description adds no information about the parameters. It mentions statistics_id and node_id only in the context of output, leaving all parameter semantics unaddressed. This severely hinders correct tool invocation.

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

Purpose4/5

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

The description clearly states the action ('browse tables') and the context ('within an IDESCAT statistic node'), distinguishing it from sibling tools like idescat_list_nodes and idescat_list_statistics. However, 'browse' is somewhat vague; explicitly stating 'list tables' would improve clarity.

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?

The description provides explicit usage guidance by directing the agent to use the returned IDs with idescat_list_table_geos before metadata or data calls, establishing a clear sequence for tool use. It does not, however, specify when not to use this tool or compare it with alternatives like idescat_get_table_metadata.

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

idescat_search_tablesidescat.search_tablesA

Topic discovery for IDESCAT Tables v2. Search by subject and optional geography words or named places such as comarca, municipi, Maresme, Barcelonès, or Girona. Common semantic aliases such as taxa atur, paro, renda per capita, family income, and poblacio municipal can be used directly. Prefer results whose geo_candidates include the requested geo_id, then confirm with idescat_list_table_geos. Reuse the returned statistics_id, node_id, and table_id with idescat_list_table_geos. Search/list provenance is discovery-only; cite idescat_get_table_metadata or the metadata resource.

ParametersJSON Schema

Name	Required	Default
`lang`	No	ca
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, so the description carries full burden. It states the tool is for discovery-only, implying read operation, and details behavior like semantic alias support and geo_candidate preference. Does not mention rate limits or auth, but adequately explains core behavior.

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

Conciseness4/5

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

Five sentences packed with information, front-loaded with purpose. Efficiently includes usage instructions and links to sibling tools. Could be slightly more concise but overall well-structured.

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

Completeness4/5

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

Given the presence of an output schema (not shown), the description covers purpose, usage flow, and provenance. It references related tools and provides enough context for a search/discovery tool. Minor gaps in parameter details but complete for typical use.

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

Parameters3/5

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

Schema coverage is 0%, so description must compensate. It adds meaning for 'query' parameter with examples and semantic aliases, but does not describe 'lang' or 'limit' parameters beyond their schema. Partial compensation for missing schema documentation.

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?

The description clearly states the tool is for 'Topic discovery for IDESCAT Tables v2' with specific verb 'search' and resource 'IDESCAT tables'. It distinguishes from sibling tools like idescat_list_tables and idescat_get_table_data by emphasizing discovery and provenance.

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?

Provides explicit guidance on preferring geo_candidates and confirming with idescat_list_table_geos, and notes that search is discovery-only, recommending citation of metadata tools. Lacks explicit when-not-to-use scenarios but gives clear context.

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

pingPingA

Check that the Catalunya Open Data MCP server is running.

ParametersJSON Schema

Name	Required	Description	Default
`name`	No	Optional name to include in the response.

Output Schema

ParametersJSON Schema

Name	Required	Description
`server`	Yes
`message`	Yes

TDQS

A3.7/5.0

Behavior2/5

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

No annotations provided; description only states purpose without disclosing side effects, return format, or behavior of the optional 'name' parameter.

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?

Single concise sentence that is front-loaded with the tool's purpose.

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

Completeness5/5

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

For a simple health check tool with one optional parameter, the description is sufficiently complete, and output schema handles return values.

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

Parameters3/5

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

Schema has 100% coverage for the single optional parameter; description adds no additional meaning.

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?

The description clearly states the tool checks server health, distinguishing it from the sibling data query tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Implied usage as a health check, but no explicit guidance on when to use or not use compared to siblings.

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

socrata_describe_datasetsocrata.describe_datasetA

Describe a Catalunya open data Socrata dataset, including queryable API field names.

ParametersJSON Schema

Name	Required	Description	Default
`source_id`	Yes	Socrata dataset identifier, such as v8i4-fa4q.

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It indicates a read-only metadata operation, but does not mention any specific behavioral traits such as authentication needs, rate limits, or whether the operation is safe/idempotent. The description is adequate but minimal.

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

Conciseness4/5

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

The description is a single sentence with no redundant words. It is front-loaded with the core action and resource. Slight improvement could be made by adding structure (e.g., listing what is returned), but overall it is efficient.

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

Completeness4/5

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

The tool is simple with one parameter and an output schema, so the description does not need to explain return values. The description is sufficient for understanding the tool's purpose, though it could briefly mention that the output contains metadata and field names.

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

Parameters3/5

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

The schema has 100% coverage for the single parameter source_id, and its description provides an example identifier. The tool's description adds context about 'Catalunya open data Socrata dataset' but does not add new semantic meaning beyond what the schema already provides. Baseline score is appropriate.

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?

The description clearly states the verb 'describe' and the resource 'Catalunya open data Socrata dataset', specifying that it includes queryable API field names. This distinguishes it from sibling tools like socrata_query_dataset and socrata_search_datasets, which handle querying and searching respectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The description implies usage for obtaining dataset metadata and field names, but does not explicitly state when to use this tool versus alternatives (e.g., socrata_query_dataset for data queries or bcn_query_resource for general resource info). No when-not-to-use guidance is provided.

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

socrata_query_datasetsocrata.query_datasetA

Query rows from a Catalunya open data Socrata dataset. Always call socrata_describe_dataset first and use returned field_name values, not display_name values. Pass clause values only, for example where: "municipi = 'Girona'"; never pass ?$where=... URL fragments. Supply order whenever using offset for stable pagination; without it, repeated calls may return duplicate or missing rows. Prefer narrowing filters or reducing $select over raising limit. Server caps row count and response bytes; truncation is signaled explicitly. Aggregate queries combine select with aggregate functions and group.

ParametersJSON Schema

Name	Required	Description
`group`	No	Raw SODA $group clause value for aggregate queries.
`limit`	No	Rows to return. Server maximum: 100.
`order`	No	Raw SODA $order clause value. Supply this when using offset.
`where`	No	Raw SODA $where clause value using field_name values from describe.
`offset`	No	Zero-based row offset for pagination.
`select`	No	Raw SODA $select clause value using field_name values from describe.
`source_id`	Yes	Socrata dataset identifier, such as v8i4-fa4q.

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

A4.5/5.0

Behavior5/5

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

Despite no annotations, the description fully discloses key behaviors: server caps on rows/bytes, truncation signaling, aggregate query patterns, and stability requirements for pagination. No contradictions exist.

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?

Six concise sentences with front-loaded purpose. Every sentence adds unique value: prerequisite, usage rules, pagination, limits, aggregates. No redundancy.

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

Completeness5/5

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

Covers prerequisite (describe), query construction, pagination, limits, aggregates, and example. Output schema likely handles return values; no gaps for a query tool.

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

Parameters3/5

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

Schema already describes each parameter (100% coverage), so description adds limited semantic value. Usage patterns like passing clause values only and needing order with offset are helpful but not parameter-specific meaning.

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?

The description clearly states the tool queries rows from a Catalunya open data Socrata dataset, distinguishing it from siblings like socrata_describe_dataset and socrata_search_datasets.

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 advises calling socrata_describe_dataset first and using field_name values, provides rules for order with offset, and recommends narrowing filters. Lacks explicit when-not-to-use but offers strong contextual guidance.

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

socrata_search_datasetssocrata.search_datasetsB

Discover dataset IDs and metadata from the Catalunya open data Socrata catalog.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of datasets to return. Server maximum: 100.
`query`	Yes	Search text for the Socrata catalog.
`offset`	No	Zero-based result offset for pagination.

Output Schema

ParametersJSON Schema

Name	Required	Description
`data`	Yes
`error`	No
`provenance`	Yes

TDQS

B3.3/5.0

Behavior2/5

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

With no annotations, the description carries full burden. It mentions discovery of metadata but does not disclose behavioral traits like read-only nature, pagination behavior, or what happens with empty results. The existence of offset/limit parameters is not highlighted.

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?

The description is a single, front-loaded sentence that conveys the core purpose efficiently with no wasted words.

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?

Given the output schema exists, the description is minimally adequate but lacks details on return format, pagination, and expected behavior. For a search tool with 3 parameters and pagination support, more context would improve completeness.

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

Parameters3/5

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

Schema coverage is 100%, so the description adds limited value beyond the schema. It provides context about the catalog source but does not elaborate on parameter usage or format beyond the schema definitions. Baseline 3 is appropriate.

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?

The description clearly states the verb 'Discover' and the resource 'dataset IDs and metadata' from a specific catalog (Catalunya open data Socrata). It distinguishes this search tool from siblings like 'socrata_describe_dataset' and 'socrata_query_dataset' by focusing on discovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives (e.g., when to search vs describe vs query). Context signals show sibling tools, but the description does not provide exclusion criteria or comparison.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

22 tool updatesv0.1.4Jul 12, 2026
- First observedbcn_answer_city_query
- First observedbcn_execute_city_query
- First observedbcn_get_package
- First observedbcn_get_resource_info
- First observedbcn_plan_query
- First observedbcn_preview_resource
- First observedbcn_query_resource
- First observedbcn_query_resource_geo
- First observedbcn_recommend_resources
- First observedbcn_resolve_place
- First observedbcn_search_packages
- First observedidescat_get_table_data
- First observedidescat_get_table_metadata
- First observedidescat_list_nodes
- First observedidescat_list_statistics
- First observedidescat_list_table_geos
- First observedidescat_list_tables
- First observedidescat_search_tables
- First observedping
- First observedsocrata_describe_dataset
- First observedsocrata_query_dataset
- First observedsocrata_search_datasets

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored 2026-07-12 23:10 across 22 tools

Disambiguation5/5

Each tool has a clear, distinct purpose within its data source group (BCN, IDESCAT, Socrata). Tools like bcn_plan_query, bcn_execute_city_query, and bcn_answer_city_query are complementary, not overlapping. Cross-group tools are clearly differentiated by prefix.

Naming Consistency5/5

Tool names follow a consistent pattern: {source_prefix}_{verb}_{noun}. For example, bcn_search_packages, idescat_get_table_metadata, socrata_describe_dataset. Naming conventions are uniform and predictable, aiding agent selection.

Tool Count4/5

22 tools is relatively high but justified by covering three distinct data platforms (BCN, IDESCAT, Socrata) with full discovery and query workflows. Each tool serves a specific step, and the count aligns with the server's broad scope.

Completeness5/5

For each data source, the tools cover the full lifecycle: discovery (search, list, recommend), metadata inspection, query execution, and specific operations like geospatial queries and place resolution. No obvious gaps in functionality.

Maintenance

ActivityInactive

ResponsivenessResponsive

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Idescat MCP Server A
cat.idescat
Query official statistics of Catalonia (Idescat): tables, metadata and JSON-stat data via MCP.
Government Data Open Data
71
opendata-cat A
io.github.xaviviro
15 Catalan portals + radio archive: gov, INE/REE/CNMC, CORA, Catalònica, radioteca.cat.
Open Data Government Data Search
8221
socrata-mcp-server A
io.github.cyanheads
Search and query government open-data portals (Socrata SODA API).
Government Data Open Data
623
Nova Scotia Data Explorer A
io.github.SevaSk
Query and explore Nova Scotia open datasets via the Socrata SODA API.
Open Data Government Data Search
42

Related MCP Servers

idescat-mcp
Government Data Open Data Search
catbru
F
license
A
quality
D
maintenance
Provides access to Catalonia's statistical data via the IDESCAT Tables API v2. It enables users to navigate catalogs, inspect metadata, and query data with territorial filters and resolved labels.
Updated 6 months ago (2026-03-20 01:20 UTC)
5
1
-
Datos.gob.es-MCP
Government Data Open Data
AnCode666
A
license
A
quality
C
maintenance
Enables querying and analyzing over 90,000 public datasets from the Spanish Government Open Data Portal (datos.gob.es) using natural language, with tools for search, filtering, metadata access, and SPARQL queries.
Updated a year ago (2025-10-05 10:54 UTC)
10
5
MIT
CKAN MCP Server
Government Data Open Data
ondata
A
license
A
quality
A
maintenance
Enables AI assistants to search, explore, and query any CKAN open data portal through natural language, making public datasets accessible without requiring knowledge of the portal's API.
Updated 14 hours ago (2026-09-08 18:07 UTC)
20
1,604
57
MIT
Opendata.cat MCP Server
Open Data Government Data
xaviviro
A
license
A
quality
C
maintenance
Connects LLMs to over 2,850 datasets from 13 Catalan and Spanish open data portals, enabling natural language search and real-time queries of public data.
Updated a month ago (2026-07-30 10:57 UTC)
8
92
21
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aalises/catalunya-opendata-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Catalunya Open Data MCP

Why This Exists

Requirements

Install

Connect an MCP Client

MCP Surface

Tools

Prompts

Resources

Socrata Workflow

1. Search

2. Describe

3. Query

4. Attach Metadata

5. Cite

IDESCAT Workflow

Open Data BCN Workflow

1. Recommend Or Search

2. Plan Or Execute A City Question

3. Inspect A Resource

4. Query Active DataStore Resources

5. Resolve Named Places

6. Query Resources Geospatially

7. Preview Inactive CSV/JSON Resources

Query Safety

Configuration

Development

Evaluations

Release Checklist

Project Notes

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API