This is a collection of 8 example MCP servers, each implementing read-only lookups or smart-home control. Tool naming is mostly verb-first and clear (find_*, get_*, set_*, turn_off). Descriptions are present but vary in depth, most are 50 - 150 chars, adequately explaining the tool's purpose. However, parameter descriptions are inconsistent: some params like 'articleNumbers', 'fundingType', and 'targetAudience' have good descriptions; others like 'page' and 'sort' are minimal. Input schemas are visible and properly typed (string, number, array), but output schemas are NOT documented, critical omission for LLM understanding. No error handling guidance visible. Tool #1 - #6 are read-only and well-scoped; tools #7 - #8 (Philips Hue control) are WRITE operations but lack idempotency hints, confirmation patterns, or destructive-operation warnings. This is a teaching/example repo, not production-grade, but the foundation is solid.

• Document output schema for every tool. Example for find_company: 'Returns: {companies: [{name: string, registerNumber: string, address: string, status: string}], totalCount: number}'
• Add readOnlyHint to all 6 lookup tools (find_*, get_*) and destructiveHint to Philips Hue controls (set_light, turn_off).
• For Philips Hue tools, add idempotentHint=false and a note: 'Calling set_light twice with the same brightness/color is safe, but turn_off is fire-and-forget. Consider a 'get_light_state' tool to verify state before controlling.'
• Add error recovery guidance: 'If no results found, try a broader search term or check company name spelling. Available states: Austria, Burgenland, ...'
• Declare enum parameters in JSON Schema (type: 'string', enum: ['...']) rather than inline text. This lets MCP clients and LLMs enumerate valid values programmatically.
• For set_light, add validation: 'brightness: integer 0 - 100. color: web color name (red, blue, hotpink, ...) OR hex #RRGGBB. Invalid colors return a list of suggestions.'
• Add per-tool documentation of rate limits, latency SLAs, or unavailability behavior (e.g. 'klimaaktiv lookup may be unavailable 2 - 4 AM CET; returns error if service is down').
• Batch variants: If agents typically search multiple companies, offer find_companies_batch accepting a list of names, returning results in parallel.
• For turn_off, consider a confirmation pattern: add an optional confirm_immediately=false parameter. If false, the tool returns a confirmation request; if true, it executes immediately. Prevents accidental bulb shutoffs.