Swiss Democracy MCP demonstrates solid tool design with consistent naming patterns (all verb_noun: search_*, get_*, list_), complete input schemas with enums and descriptions, and clear documentation of data sources. All 10 tools have descriptions (avg 120 chars) and typed parameters. However, output schemas are not explicitly documented in the source code, only inferred from descriptions. Error handling is basic (ToolError raised but recovery guidance missing). No tool annotations visible (readOnlyHint, destructiveHint, idempotentHint). Parameter descriptions are adequate but lack format constraints (e.g., vote_number format '1995-01' stated in description but not in schema). Missing dependency hints for multi-step workflows (e.g., search before get_detail).

• Add explicit output schemas to each tool definition. Document response fields (e.g., 'Returns: {total_count: int, matches: [{vote_number: str, title: str, date: str, result: str}], next_page: str|null}').
• Declare tool annotations: add readOnlyHint=true to all 10 tools in the tool registration to signal safety to LLMs.
• Enhance parameter descriptions with format constraints. For vote_number, add '(format: YYYY-NN, e.g. 1995-01)'. For result_url, add '(must be from opendata.swiss domain)'.
• Implement actionable error messages. When vote_number not found, return: 'Vote 1995-99 not found. Try democracy_search_votes(keyword="...", year_from=1995, year_to=1995) to find valid vote numbers.'
• Add dependency hints to tool descriptions. E.g., democracy_get_vote_detail: 'If you only have a keyword or year, call democracy_search_votes() first to obtain the vote_number.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry