The Smartling MCP server has 27 tools with basic parameter schemas and descriptions, but exhibits significant quality gaps across definition dimensions. All tools have descriptions (good), but many are generic and lack the specificity needed for LLM tool selection. Input schemas are present and typed, but lack proper structure documentation. Output schemas are entirely undocumented, the server provides no specification of what data structure each tool returns, forcing LLMs to guess. Error handling is minimal; most tools offer no recovery guidance. Tool naming is generally verb-noun compliant (get_, create_, delete_), but many parameters are underspecified with respect to constraints, formats, and mutual dependencies. No tool demonstrates the full pattern adherence expected at higher quality tiers. Most tools cluster in the 35-50 range due to missing output documentation and incomplete parameter descriptions.
Output schemas completely undocumented, no tool specifies what it returns. LLMs cannot plan subsequent operations or extract needed fields. This is a critical blocker for agentic use.
Document output schema for every tool. Specify the structure, field types, and which fields are critical for downstream tool calls. Example: 'Returns {projects: [{id: string, name: string, sourceLocale: string, targetLocales: string[]}], total: number}'
Enhance parameter descriptions with format constraints and examples. For 'projectId', write: 'The Smartling project ID (e.g., a-1234567-b). Use smartling_get_projects to discover valid IDs.'
For array parameters, document element type and constraints. E.g., 'targetLocaleIds: array of locale codes in format xx-YY (e.g., ["en-US", "fr-FR"]). Maximum 50 locales.'
Add pagination support and parameters to list operations. Include 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters. Return 'total' or 'has_more' in the response.
For destructive tools (delete_file, delete_glossary_term, delete_webhook), add a 'confirm' boolean parameter or offer a dry-run variant. Document: 'This operation is irreversible. Pass confirm=true to proceed.'
Add error handling guidance to tool descriptions. Example: 'If the file type is unsupported, returns error code 400 with a list of supported types. Retry with a different fileType.'
Clarify tool selection logic in descriptions. Example for get_file_status: 'Use to check translation progress (completion %). Use smartling_run_quality_check to validate translation quality.'
Add tool annotation hints in the schema. Mark read-only tools with readOnlyHint: true, destructive tools with destructiveHint: true, and idempotent operations with idempotentHint: true.
Parameter descriptions are generic and lack specificity. For example, 'The project ID' does not explain the format, length, or constraints. 'fileUri' has no guidance on valid formats or examples. 'localeIdsToAuthorize' lacks description of expected array structure and locale format (e.g., en-US vs en_US).
Destructive and reversible operations (delete_file, delete_glossary_term, delete_webhook, cancel_job) lack confirmation or dry-run patterns. Tools marked as DESTRUCTIVE should offer a confirmation step before executing.
No error handling guidance. Tools do not document what errors are possible, how to interpret them, or what the LLM should do next. E.g., if uploading a file fails due to invalid locale, the tool should suggest recovery steps.
No pagination parameters documented for list operations (get_projects, get_jobs, get_glossaries, get_webhooks, search_strings, get_quality_results). These tools likely return large result sets but provide no way to limit or paginate, risking context window exhaustion.
Array parameters (localeIdsToAuthorize, targetLocaleIds, fileUris, events) lack documentation of expected element type, format, and constraints. E.g., are locale IDs 'en-US' or 'en_US'? What is the max array length?
Tool descriptions do not explain when to use one tool vs. a similar tool. E.g., what is the difference between smartling_get_file_status and smartling_get_quality_results? When should an LLM call each?
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) visible in schema. These hints help LLMs reason about safety and retry logic.
all 27 tools
Document locale format conventions. If Smartling uses 'en-US' format, state this explicitly: 'Locale format: LANGUAGE-COUNTRY (e.g., en-US, fr-FR, de-DE).'
For fileUri and fileType parameters, provide constraints. Example: 'fileUri must be unique within the project. fileType must be one of: json, xml, po, ts, xliff, properties.'
Add required field constraints to parameter descriptions. Mark which parameters are mutually exclusive or dependent.
Include chaining IDs in responses. If a tool creates a job, return both jobId and projectId so the LLM can immediately call smartling_add_files_to_job without a lookup.