|
| 1 | +# TigerData MCP Feedback |
| 2 | + |
| 3 | +## Overall Assessment |
| 4 | +The TigerData MCP tools provide useful database management functionality but have several areas for improvement in naming consistency, parameter documentation, and descriptions. |
| 5 | + |
| 6 | +## Tool Names |
| 7 | + |
| 8 | +### Issues |
| 9 | +1. **Inconsistent naming conventions**: Mixed use of camelCase (`getGuide`) and snake_case (`service_list`, `semantic_search`) creates unpredictability |
| 10 | +2. **Verb consistency**: Some tools use action verbs (`create`, `list`) while others use descriptive terms (`show` instead of `get`) |
| 11 | + |
| 12 | +### Recommendations |
| 13 | +- **WHY**: Consistency reduces cognitive load and makes the API more predictable |
| 14 | +- Standardize on snake_case throughout: `get_guide`, `semantic_search_postgres_docs` |
| 15 | +- Use consistent verbs: `service_get` instead of `service_show` for alignment with REST conventions |
| 16 | + |
| 17 | +## Input Parameters |
| 18 | + |
| 19 | +### `mcp__tigerdata__getGuide` |
| 20 | +**Issue**: Parameter `prompt_name` is misleading - these are guides, not prompts |
| 21 | +**Recommendation**: Rename to `guide_name` or `guide_id` |
| 22 | +**WHY**: Clear naming prevents confusion about what values are expected |
| 23 | + |
| 24 | +### `mcp__tigerdata__semanticSearchPostgresDocs` |
| 25 | +**Critical Issues**: |
| 26 | +1. Parameter type confusion: `version` marked as required but allows null |
| 27 | +2. Type mismatch: PostgreSQL versions like "17.2" need string type, not integer |
| 28 | +**Recommendations**: |
| 29 | +- Make `version` and `limit` truly optional by removing from required array |
| 30 | +- Change `version` to string type |
| 31 | +**WHY**: Prevents runtime errors and failed API calls |
| 32 | + |
| 33 | +### `mcp__tigerdata__service_create` |
| 34 | +**Strengths**: Excellent use of enums, clear defaults, good examples |
| 35 | +**✅ IMPLEMENTED**: Renamed `timeout` parameter to `timeout_minutes` for clarity |
| 36 | +**Result**: Parameter name now explicitly indicates units, preventing confusion. |
| 37 | + |
| 38 | +### `mcp__tigerdata__service_update_password` |
| 39 | +**Missing**: No password strength requirements documented |
| 40 | +**Recommendation**: Add validation rules (min length, character requirements) to description |
| 41 | +**WHY**: Prevents failed attempts due to weak passwords |
| 42 | + |
| 43 | +## Descriptions |
| 44 | + |
| 45 | +### Excellent Examples |
| 46 | +- `service_create`: Clear billing warnings, thorough wait/timeout explanation |
| 47 | +- `getGuide`: Upfront listing of all available guides |
| 48 | + |
| 49 | +### Needs Improvement |
| 50 | + |
| 51 | +1. **`semanticSearchPostgresDocs`** |
| 52 | + - Missing: Return format, number of results, relevance scoring |
| 53 | + - **Recommendation**: "Searches PostgreSQL docs using semantic similarity. Returns up to N results with content, metadata, and distance scores (lower = more relevant)" |
| 54 | + - **WHY**: Users need to understand what they'll receive |
| 55 | + |
| 56 | +2. **`service_list`** |
| 57 | + - Unclear: How is "current project" determined? |
| 58 | + - **Recommendation**: Specify if from auth context or parameter |
| 59 | + - **WHY**: Ambiguity about data scope causes confusion |
| 60 | + |
| 61 | +## Functionality Testing Results |
| 62 | + |
| 63 | +### Working Well |
| 64 | +- All tested tools executed successfully |
| 65 | +- Response times were reasonable |
| 66 | +- JSON responses well-structured |
| 67 | + |
| 68 | +### Issues Discovered |
| 69 | + |
| 70 | +1. **Guide Content Length**: The `setup_hypertable` guide returns 15,000+ characters |
| 71 | + - **Impact**: Can consume significant LLM context |
| 72 | + - **Recommendation**: Break into smaller focused guides or add length warnings |
| 73 | + - **WHY**: Prevents context exhaustion in conversations |
| 74 | + |
| 75 | +2. **Missing Error Documentation**: No information about possible error codes or formats |
| 76 | + - **Recommendation**: Add common error scenarios to each tool description |
| 77 | + - **WHY**: Enables proper error handling |
| 78 | + |
| 79 | +## Missing Critical Functionality |
| 80 | + |
| 81 | +1. **No service deletion**: Can create but not remove services |
| 82 | +2. **No pause/resume**: Response shows "paused" field but no control mechanism |
| 83 | +3. **No SQL execution**: Can't run queries against created services |
| 84 | +4. **No connection string helper**: Users must construct connection strings manually |
| 85 | + |
| 86 | +**WHY THESE MATTER**: Complete lifecycle management requires all CRUD operations |
| 87 | + |
| 88 | +## Schema Design Observations |
| 89 | + |
| 90 | +### Resource Format Inconsistency |
| 91 | +- **Input**: `"cpu_memory": "0.5 CPU/2GB"` (combined string) |
| 92 | +- **Output**: `{"cpu": "0.5 cores", "memory": "2 GB"}` (separate fields) |
| 93 | +- **Impact**: Requires different parsing logic for input vs output |
| 94 | +- **Recommendation**: Use consistent format or document the rationale |
| 95 | +- **WHY**: Reduces implementation complexity |
| 96 | + |
| 97 | +## Specific Priority Improvements |
| 98 | + |
| 99 | +### High Priority |
| 100 | +1. Fix parameter type issues in `semanticSearchPostgresDocs` |
| 101 | +2. Standardize naming conventions across all tools |
| 102 | +3. Add service deletion capability |
| 103 | +4. ~~Rename timeout to timeout_minutes~~ ✅ COMPLETED |
| 104 | + |
| 105 | +### Medium Priority |
| 106 | +1. Document return formats in all descriptions |
| 107 | +2. Add error code documentation |
| 108 | +3. Break up large guide content |
| 109 | + |
| 110 | +### Low Priority |
| 111 | +1. Add filtering to `service_list` |
| 112 | +2. Include connection string formatting helper |
| 113 | +3. Add dry-run options for destructive operations |
| 114 | + |
| 115 | +## Positive Highlights |
| 116 | +- Excellent enum usage for constrained choices |
| 117 | +- Good use of JSON Schema for validation |
| 118 | +- Clear billing warnings where appropriate |
| 119 | +- Well-structured responses with consistent formatting |
| 120 | +- Semantic search provides relevant, useful results |
| 121 | +- Good use of defaults to simplify common cases |
| 122 | + |
| 123 | +## Why These Improvements Matter |
| 124 | +1. **Predictability**: Consistent naming reduces learning curve |
| 125 | +2. **Reliability**: Proper typing prevents runtime failures |
| 126 | +3. **Usability**: Clear documentation reduces trial-and-error |
| 127 | +4. **Completeness**: Full CRUD operations enable real workflows |
| 128 | +5. **Efficiency**: Appropriate content sizing preserves LLM context |
0 commit comments