cartographer-mcp demonstrates solid fundamentals: all 6 tools follow verb_noun naming (list_services, get_dependencies, refresh_cache, etc.), all have non-trivial descriptions (65-85 chars), and input schemas are properly defined with typed parameters. However, output schemas are undocumented, tools return JSON responses but no formal output schema is declared. Parameter descriptions are present but minimal (5-40 chars), lacking actionable detail on formats, constraints, and expected values. Error handling is present but generic ('service not found', 'failed to marshal') without recovery guidance. No tool annotations (readOnlyHint/destructiveHint) despite clear READ_ONLY vs WRITE semantics. Missing pagination guidance for list_services despite domain patterns suggesting large result sets. Composition is strong, tools are single-responsibility and chain well (search_services → get_service → get_dependencies). Security is acceptable for a read-mostly server with one WRITE operation (refresh_cache).

• Document output schemas formally. For each tool, declare a response schema (e.g., list_services returns {cache_age_seconds: number, refreshed_at: string, services: [{name, type, lifecycle, archived}], total: number}). Include required vs optional fields.
• Enhance parameter descriptions with enum values and constraints. For list_services 'type' and 'lifecycle': specify 'Filter by service type (e.g. backend, frontend, data, infrastructure)' or provide explicit enums. For refresh_cache 'groups': specify 'Comma-separated GitLab group paths (max 10, e.g. acme/backend, acme/frontend)'.
• Add tool annotations to all tools. Use mcp.WithReadOnly() for read-only tools and document destructiveHint=true for refresh_cache. This guides agent retry logic and safety decisions.
• Improve error messages with actionable recovery. When a service is not found, return the fuzzyMatch() suggestions in the response and guide: 'Service not found. Did you mean: [suggestions]. Or call search_services("query") to find by keyword.'
• Add pagination to list_services. Include page (default 1), limit (default 20, max 100) parameters. Return total count and indicate if more results exist. Document in description: 'Returns up to 20 services per page. Large catalogs require pagination.'
• Return chaining IDs. In get_service response, include project.id or project.path_with_namespace so that downstream tools (get_dependencies, refresh_cache) can directly reference the result.
• Add description fields to help LLM selection. Currently 'get_dependencies' and 'get_dependents' descriptions are identical except for direction, clarify when to use each: 'Use get_dependencies to find what this service calls (forward/outbound). Use get_dependents to find what calls this service (reverse/inbound).'