The server defines 10 tools with complete JSON schemas and basic descriptions. All tools are explicitly registered in setupToolHandlers() with inputSchema objects. However, descriptions are generic and lack LLM-optimized guidance on when/why to use each tool. Parameter descriptions are minimal (1-10 words). No output schemas are documented. Error handling is absent from tool definitions. Naming is mostly clear (verb_noun pattern) but some tools have overlapping responsibilities (start/stop project vs start/stop services). No parameter validation constraints (enums, ranges) beyond type declarations. The server lands in the 'fair/poor' range, definitions are functional but would not pass production code review.
Tools (10)
rolldev_composerwritesource verified71/100
Run Composer commands inside the php-fpm container
No output schemas documented. Tools execute commands and return unstructured stdout/stderr but provide no schema for the response. LLMs cannot plan downstream calls or extract structured data. This violates pattern:response-shaper and pattern:tool baseline requirements.
Descriptions lack LLM-optimized guidance. Most descriptions (e.g., 'Start a RollDev project environment', 'Stop RollDev system services') are 4-10 words and do not answer: WHAT does it do? WHEN should the LLM call it? WHAT does it return? This violates pattern:tool-description baseline expectations (avg 194 chars for A+ tools).
Add output schema documentation to all tools. Document whether responses return stdout/stderr, structured JSON, or both. Example: { type: 'object', properties: { success: boolean, output: string, errors: string[] } }
Expand tool descriptions to 50-200 characters following pattern:tool-description. Template: '[ACTION] [RESOURCE]. Use this when [WHEN]. Returns [WHAT]. Prerequisites: [IF ANY].' Example: 'Start a stopped RollDev project environment, initializing containers and services. Use this to resume development after stopping. Returns start status and container IDs. Requires project_path to be a valid RollDev project directory.'
Add detailed parameter descriptions (60-100 chars each) with format, validation rules, and error cases. Example: 'Absolute path to the RollDev project root (must exist, must contain .rolldev/config). Relative paths are not supported. Returns error if path is invalid or not a RollDev project.'
Add enum constraints to string parameters where applicable. For rolldev_db_query.database, declare enum: ['magento', 'magento_test', 'custom_db'] or provide a discovery tool to list available databases.
Add pattern validation to rolldev_magento2_init.project_name via JSON Schema: pattern: '^[a-z0-9-]+$'. Add pattern for magento_version: pattern: '^\d+\.\d+(\.\d+)?(-p\d+)?$|^\d+\.\d+\.x$' to match '2.4.x', '2.4.7', '2.4.7-p3'.
Document error handling and recovery for destructive tools. Add error_handling section to tool definitions: { retryable: boolean, user_fixable: boolean, recovery_hint: string }. Example for stop_project: 'If project fails to stop, check rolldev status. Container may be stuck, try force_stop. Stopping cannot be undone (no undo tool available).'
Parameter descriptions are minimal or missing context. E.g., 'project_path' is described as 'Path to the project directory' (4 words) without format guidance (absolute vs relative), validation rules, or error cases. Parameter descriptions should average 70+ chars and explain constraints, not just name the field.
No enum constraints on freeform string parameters. 'database' parameter in rolldev_db_query defaults to 'magento' but accepts any string, LLMs may pass invalid database names. Should declare valid enum values or validation regex.
No error handling guidance in tool definitions. Tools that execute destructive commands (stop_project, stop_svc, db_query, composer update) provide no recovery hints, retryability classification, or confirmation mechanisms. This violates pattern:recovery-guide and pattern:confirmation-request.
Overlapping tool responsibilities. rolldev_start_svc and rolldev_stop_svc appear to manage services, while rolldev_start_project and rolldev_stop_project manage projects. The distinction is unclear, does 'project' include services? Can they operate independently? Naming should disambiguate (e.g. 'project_services' vs 'system_services').
No pagination support for rolldev_list_environments. If this returns many environments, the response could exceed token budgets. Should include limit/offset parameters and return a total count. Violates pattern:paginated-result.
No validation of magento_version format in rolldev_magento2_init. Description provides examples ('2.4.x', '2.4.7-p3') but no regex pattern or enum constraint. LLMs could pass invalid versions like '2.4.abc' or '1.0'.
project_name in rolldev_magento2_init has constraints ('lowercase letters, numbers, and hyphens only') stated only in description text, not as a JSON Schema pattern. LLMs cannot reliably parse natural-language constraints, must be enforced via regex pattern in the schema.
rolldev_magento2_init
Add dry-run or confirmation parameters to destructive tools (stop_project, stop_svc, db_query with DELETE/DROP). Example: { confirm: boolean, dry_run: boolean } to enable pattern:confirmation-request.
Add pagination to rolldev_list_environments: introduce limit (default 20, max 100) and offset parameters. Return { environments: [...], total: number, limit: number, offset: number }.
Clarify tool composition and responsibility. Split rolldev_start_svc/rolldev_stop_svc into project-scoped equivalents (rolldev_start_project_services, rolldev_stop_project_services) if they are project-dependent. Document whether services can operate independently of projects.
Document the response structure for list_environments. Specify: 'Returns a list of running environments. Each entry contains: project_path (string), status (string: running|stopped), container_id (string), services (array of service names). Example: { environments: [ { project_path: '/home/user/magento-project', status: 'running', container_id: 'abc123', services: ['php-fpm', 'mysql', 'redis'] } ], total: 1 }'
Add security/audit notes if sensitive (db_query, php_script allow code execution). Specify: 'Executes arbitrary SQL/PHP, ensure project_path is trusted. All calls are logged. Destructive queries (DROP, DELETE, TRUNCATE) require human approval in production.'
Document dependencies between tools in descriptions. E.g., for rolldev_magento_cli: 'Requires project to be running (see rolldev_start_project). Use rolldev_list_environments to find available projects first.'