borme-mcp has 7 tools with visible definitions in server.py. All tools are READ_ONLY and have descriptions, which is good. However, there are consistent gaps: (1) Most parameter descriptions are minimal and lack format/constraint details (e.g., 'date_from' says 'Start date in YYYY-MM-DD format' but no validation guidance); (2) No output schemas documented, tools return JSON strings with implicit field structures; (3) No error handling patterns visible, tools return generic JSON with 'error' or 'found': false, but no recovery guidance; (4) Parameter descriptions are brief (averaging ~40-50 chars), below the 72-char baseline; (5) Tool names lack action verbs consistently (e.g., 'recent_signals' is noun-heavy, 'registry_stats' is noun-only). Positives: All tools have substantive docstrings (100-200 chars), parameter types are declared in function signatures, all tools are marked READ_ONLY, tools accept natural identifiers (company names, not just slugs), and the server includes sensible defaults (limit capping, accent-insensitive province matching).

• Add formal output schemas to each tool. Document the JSON structure returned (e.g., for search_events: {count: int, events: [{event_id: str, date: str (ISO 8601), borme_id: str, province: str, company_name: str, company_slug: str, acts: [{act_type: str, act_type_raw: str, roles?: array, payload?: object}], registral: str}]}). This can be a docstring annotation or a JSON Schema comment.
• Enhance parameter descriptions with actionable constraints. For 'date_from' and 'date_to', specify: 'YYYY-MM-DD format. Coverage: 2009 onwards. Both dates inclusive. If date_from > date_to, returns empty results.' For 'limit', specify: 'Integer, 1 - 200 (capped by server config, default 50). If omitted, defaults to 50.'
• Add enum constraints to the schema. For 'provinces', declare as an enum with FastMCP (e.g., @mcp.tool(params={provinces: {type: 'array', items: {enum: [list of valid province names]}}}) or document valid values explicitly. For 'act_types', provide the authoritative list in the description or as a schema enum.
• Implement systematic error handling. Define a standard error response format: {error: str, code: str, recoverable: bool, suggestion: str}. E.g., company_history('INVALID-SLUG') should return {error: 'Company not found', code: 'NOT_FOUND', recoverable: false, suggestion: 'Use search_events() to find companies matching the name, or company_by_nif() if you have a tax ID.'}
• Add pagination metadata to search_events and company_history responses. Include: total_count (approximate), returned_count, has_more: bool, next_offset: int|null. This enables agents to fetch all results without guessing.