ops-mcp demonstrates solid definition quality with complete schemas, clear descriptions, and thoughtful security patterns. All 8 tools have explicit registrations with input schemas and docstrings. Naming follows verb_noun convention (fs_search, github_list_issues, postgres_query_readonly). Descriptions are substantive (100-200 chars typical) and explain prerequisites (e.g., 'Requires OPS_MCP_GITHUB_TOKEN'). Parameters are typed and mostly described. Key strengths: sandbox validation, dry-run defaults for writes, parameterized SQL. Gaps: output schemas not formally documented in code; error handling guidance sparse; some parameter descriptions could be more prescriptive about constraints.

• Document output schemas for all tools. Add a 'Returns' section to each docstring with field names, types, and descriptions. E.g., fs_search returns {matches: [{path: string, line_number: int}], total: int, truncated: bool}.
• Add enum constraints to free-form string parameters. Change github_list_issues 'state' param to accept only 'open'|'closed'|'all'. Add min/max to numeric params: max_results 1-1000, per_page 1-100.
• Expand error handling documentation. Describe what each tool returns on failure (e.g., {error: string, code: string, retryable: bool}). Add recovery hints: 'If SQL syntax error, check parameter types match schema.'
• Enhance terse descriptions. Expand github_pr_diff_summary to: 'Fetch a PR's file-level diff summary (changed files, additions/deletions) without full patch content. Use this to understand scope before reviewing full diffs. Returns file list with stats.'
• Clarify pagination. Add to github_list_issues description: 'Results are paginated. Use per_page (1-100, default 30) and iterate via owner/repo/state/labels to fetch all pages. Returns total count if available.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry