truenas-mcp demonstrates solid definition quality with consistent naming conventions, comprehensive parameter schemas, and proper descriptions across all 11 tools. All tools use action verbs (list_, get_, start_, stop_, restart_, install_, upgrade_, rollback_). Input schemas are complete with type definitions and parameter descriptions. However, there are notable gaps: (1) output schemas are not documented in the definitions, we can infer they return JSON but the exact field structure is not specified in the source provided; (2) error handling descriptions are minimal, tools do not explain what to do if an operation fails; (3) some parameter descriptions could be more detailed about constraints and formats (e.g., 'lowercase, hyphens allowed, max 40 chars' for app_name is good, but version parameters lack format guidance). The risk annotations (READ_ONLY, WRITE, DESTRUCTIVE) are properly declared via toolAnnotations, which is a modern pattern strength. Tool composition is clean, each tool has a single responsibility. Pagination is implemented correctly on list_apps with limit/offset. The async job ID pattern (start_app, stop_app, restart_app, install_app, install_custom_app, upgrade_app, rollback_app all return job IDs) is good for non-blocking operations but lacks documentation of how to poll job status, there is no 'get_job_status' tool visible.

• Document output schemas for all tools. Specify field names, types, and nesting. Example for get_app: {"name": string, "status": string, "version": string, "container_ids": [string], "created_at": ISO8601_string}.
• Add a 'get_job_status' tool that accepts a job_id and returns {"job_id": string, "status": enum[running|succeeded|failed], "progress": integer 0-100, "error_message": string (if failed)}. Update all async tools to document that callers should use this.
• Enhance tool descriptions to include error conditions and recovery guidance. Example: 'If start_app returns a job ID, call get_job_status() to monitor completion. Common errors: app_not_found (try list_apps to verify name), insufficient_resources (check node capacity), already_running (stop_app first if needed).'
• Add format and constraint documentation to version parameters: 'Target version as semver string (e.g. 1.2.3). Call upgrade_summary() first to see available versions.'
• Add pagination to list_images: include limit (default 20, max 100) and offset (default 0) parameters. Document output includes total_count and has_more fields.
• Document custom_compose_config_string constraints: maximum size (e.g. 10 MB), required top-level 'services' key, and any unsupported Docker Compose features (e.g. build context).