FastMCP server for the Bertelsmann Datenatlas Zivilgesellschaft search API.
Server has 4 well-named search/retrieval tools with complete input schemas and reasonable descriptions. All tools follow verb_noun naming (search_*, get_*). Schemas are properly typed with descriptions for all parameters. However, output schemas are not documented, LLMs cannot predict response structure for downstream chaining. Error handling is minimal (generic RuntimeError). Parameter descriptions are functional but lack constraint details (e.g., no min/max for page/limit, no format specs for dates). Tool descriptions average ~150 chars, within baseline range, but lack WHEN-to-use guidance and dependency hints between tools.
Fetch one dataset by ID using the public CKAN-compatible package endpoint. Args: dataset_id: The dataset identifier returned by search results Returns: CKAN-compatible dataset response object
Search the piveau portal for datasets and related resources. Args: q: Free-text query, for example "climate berlin" filters: Restrict result types, for example ["dataset"] or ["dataset", "catalogue"] facets: Structured facet filters, for example {"catalog": ["city-berlin"]} page: Zero-based page number limit: Maximum number of results to return sort: Sort fields such as ["modified+desc"] show_score: Include relevance scores when available aggregation: Include facet aggregations in the response scroll: Enable scroll mode for very large result sets Returns: Search response object from the piveau search API
Run an advanced piveau search with structured filters and cursor-style pagination. Use this when the simple search tool is not enough and the query needs date ranges, bounding boxes, field selection, vocabulary filters, or explicit `searchAfter` pagination.
Continue a search that was started with `scroll=true`. Args: scroll_id: Scroll identifier returned by a previous search response Returns: The next chunk of search results
Output schemas not documented. LLMs cannot predict response structure (fields, types, nested objects) for downstream tool chaining or data extraction. Breaks pattern:tool-chain and pattern:response-shaper.
Parameter constraints missing. 'page' and 'limit' lack min/max bounds; date parameters (min_date, max_date) lack format specs (ISO 8601?); bbox coordinates lack range validation. Invites LLM to pass invalid values.
No error recovery guidance. RuntimeError with API status code and detail text is raw, does not tell LLM whether to retry, ask user, or abort. Violates pattern:recovery-guide.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | 2026-07-28+ | v2 |
Tool descriptions lack WHEN-to-use guidance. 'piveau_search_datasets_advanced' says 'use this when simple search is not enough' but does not explain which features (date ranges, bbox, scoring) solve which user intents. Agents cannot distinguish between tools.
No pagination guidance in descriptions. Tools accept 'page' and 'limit' but do not document total count, next_cursor, or result limits. Agents cannot plan multi-page retrieval or know when results are exhausted.