cluster-mcp provides 29 well-distributed tools across 6 domain servers (environment, health, news, research, socioeconomy, trade). All tools have descriptions and parameter schemas visible in the source. However, quality is inconsistent. Strengths: clear verb-prefixed naming (env_*, health_*, news_*, research_*, socio_*, trade_*), all parameters have type declarations and descriptions, structured input schemas using Zod. Weaknesses: descriptions are brief (many 50-100 chars, below the 194-char baseline), output schemas are not documented in the tool definitions, error handling strategies are not visible in the provided source, and dependencies between tools are not documented. Tools like socio_compare_regions and socio_list_semantic_ids use enums effectively (category filtering), but most tools lack constraint documentation. No evidence of pagination or result limits being enforced. Parameter naming is mostly consistent (locationId, semanticId, etc.), though some tools mix snake_case and camelCase. Security practices cannot be fully assessed from source snippets, but API keys appear injected via environment (OPENAQ_API_KEY, CONTACT_EMAIL).

• Document output schemas explicitly for all tools. Example: 'Returns: { data: [ { location_id: string, parameter: string, value: number, unit: string, timestamp: ISO8601 } ], total_count: number }'
• Expand tool descriptions to 150 - 250 characters. Include WHEN to call this tool vs. similar ones, what it requires (e.g., 'Requires a location ID from env_search_locations'), and what structure it returns.
• Add default and max limits to all limit/max parameters in descriptions. Example: 'Maximum number of results to return (default 20, max 100).'
• Create a dependency graph in the README or docs showing: env_search_locations → env_get_historical_measurements → env_get_averaged_measurements. Reference this in tool descriptions with phrases like: 'After calling this, use env_get_historical_measurements to retrieve historical data.'
• Standardize parameter naming: choose camelCase or snake_case project-wide and apply it consistently. Recommend camelCase for all params (locationId, semanticId, minCitations) for alignment with common Node.js conventions.
• Add format/constraint examples to ambiguous parameters. For 'period', document: 'Time period in ISO 8601 format (e.g., 2024-01-01/2024-01-31) or relative (last 7 days, last month).' For 'geo', specify: 'ISO 3166-1 alpha-2 country code (e.g., US, FR) or full country name.'
• For paginated results, add a note in descriptions: 'Results are paginated. Use limit and offset parameters to navigate. Total count is returned in the response.' Enforce a sensible server-side default (e.g., 20) and cap (e.g., 100).