The Civo MCP server provides 19 tools with explicit schema definitions and basic descriptions. Naming follows verb_noun conventions consistently (create_instance, list_networks, delete_cluster). However, descriptions are minimal (averaging ~30-40 chars, well below the 194-char production baseline), parameter descriptions lack detail on constraints and formats, and output schemas are not documented. Error handling is present but generic. The schema structures are properly typed and required fields are declared, which is positive; however, many parameters lack meaningful descriptive text beyond their names. This is a competent but below-average community server, functional but requiring refinement for production use.
Descriptions are critically sparse (30-40 chars vs 194-char baseline). Most descriptions are single short phrases like 'Create a new cloud instance on Civo' with no guidance on when to use, prerequisites, or what the tool returns. This forces LLMs to infer intent from names alone.
Parameter descriptions lack constraint information. The 'size' parameter accepts values like 'g2.small' but provides no guidance on valid options, format, or how to discover them. The 'region' parameter mentions 'Region identifier' with default 'LON1' but does not document valid regions or when to use each.
Expand all tool descriptions from 30 chars to 80-150 chars. Include: (1) what the tool does, (2) when to use it vs related tools, (3) what it returns. Example: 'Create a new cloud instance on Civo. Requires hostname, size, and template_id. Returns instance ID, public IP, and status. Use list_sizes to discover available instance sizes; list_disk_images to find template_id.'
Add full descriptions to all parameters. Document valid values, format, and constraints inline. Example: size parameter should say 'Instance size identifier (e.g., g2.small, g2.large). Call list_sizes to see all available options.'
Convert choice parameters to enums. Replace free-form 'region' with enum: {enum: ['LON1', 'NYC1', 'SFO1', ...]}. Replace 'size' with enum of valid instance types.
Document output schemas explicitly. Define what fields create_instance returns (id, hostname, status, public_ip, created_at, etc.) with types and descriptions. Add output schema to tool definition or return documentation.
Add dependency hints in descriptions. Example: create_instance should note 'Call list_disk_images first to find a valid template_id, or list_sizes to choose an instance size.'
Implement per-item error reporting for list operations. If list_instances encounters a region error, return results from available regions with a partial success indicator rather than failing completely.
Add confirmation step for destructive operations. Implement a dry-run flag or a separate confirm_delete_instance tool that requires an explicit confirmation token before deletion.
No output schema documentation. The code snippets show responses are formatted as text (e.g., 'Instances:\ninstance1 (id1) - status - IP'), but there is no formal schema declaring what fields are returned or their types. LLMs cannot reliably parse unstructured text responses or plan downstream tool calls.
Missing parameter descriptions in many tools. 'list_sizes' and 'list_regions' have empty property objects, so parameters lack any description text. 'list_disk_images' 'region' parameter has no description beyond the field name.
Destructive operations (delete_instance, delete_network, delete_kubernetes_cluster) lack confirmation patterns or dry-run capability. There is no mechanism to prevent accidental deletion or for the LLM to double-check before committing.
Generic error handling in CallToolRequestSchema handler. The code catches errors and likely returns them as text, but there is no guidance on error categories (retryable vs user-fixable), actionable recovery steps, or invalid value clarification. An LLM hitting an API error receives no hint on how to proceed.
No enum constraints for choice parameters. 'size' parameter should enumerate valid instance sizes (g2.small, g2.large, etc.); 'region' should list available regions instead of just saying 'Region identifier'. Free-form strings invite hallucinated values.
Parameter 'template_id' in create_instance is required but has no description of what template IDs are valid, how to discover them, or what format they take. The tool should guide users to call 'list_disk_images' first or accept template names.
Pagination support is minimal. 'list_instances', 'list_disk_images', and other list tools support page/per_page but do not document a total count or next_cursor in responses. Large result sets are not capped, risking context window exhaustion.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). The server correctly marks tools with Risk levels (READ_ONLY, WRITE, REVERSIBLE, DESTRUCTIVE) in the metadata but does not use MCP tool annotation fields. This information should be in the tool definition for proper agent handling.
Enforce and document result limits. Cap list_instances, list_disk_images, list_networks at 50 items by default. Mention the limit in the tool description and provide pagination guidance.
Add tool annotations to server capabilities. Set readOnlyHint=true for all list_* and get_* tools, destructiveHint=true for delete_*, reversibleHint=true for reboot_/shutdown_/start_. This enables agents to reason about tool safety.
Validate input early and return actionable errors. Example: if region='INVALID', return 'Invalid region INVALID. Valid regions: LON1, NYC1, SFO1' instead of a generic API error.