The Buildable MCP server has 7 tools with explicit Zod schemas visible in src/cli.ts. Naming is action-verb-based and generally clear (get_project_context, start_task, update_progress, complete_task, create_discussion, health_check). Descriptions are present for all tools and most parameters. However, several issues prevent a higher score: (1) Return schemas are not documented, tools return raw JSON.stringify() of API responses without specifying output structure; (2) Error handling is minimal, tools throw generic 'Not connected' errors but don't include recovery guidance or error classification; (3) Some parameter descriptions are generic or lack constraint detail (e.g., 'Optional notes about the task' lacks format/length guidance); (4) No parameter-level input validation or sanitization visible; (5) Complete_task and other write tools lack any confirmation/dry-run pattern despite being destructive. Tools average ~70-80 chars in description length (within baseline range of 194 chars avg but on the brief side). Schema completeness varies: update_progress has rich input schema with constraints (min/max on progress), but output schemas are entirely undocumented.

• Document output schemas for all 7 tools. Define the JSON structure (fields, types) returned by each. Use a JSDoc comment or TypeScript interface to be explicit. Example: 'Returns { task: { id: string; title: string; status: "pending"|"in_progress"|"complete" }; ... }'
• Enhance error handling: catch API errors, categorize them (network timeout → retryable; invalid task_id → user-fixable; auth failure → fatal), and return structured error responses with guidance. Example: 'Task not found. Try get_next_task() to see available tasks.'
• Add optional confirmation/dry-run parameters to destructive tools (start_task, update_progress, complete_task, create_discussion). When dry_run=true, return what would happen without actually modifying state. This lets agents verify intent before committing.
• Expand parameter descriptions to 50-200 chars and include constraints. Example: 'approach: Optional strategy for the task (max 500 chars, 1-2 sentences). E.g., "Refactor using extract-method pattern".'
• Implement input validation: sanitize string parameters, validate enum values, check numeric ranges, and return 400-style errors with the constraint violated. Example: 'Invalid progress value 150, must be 0-100.'
• Add limit/offset/page parameters to get_project_context and get_next_task. Return pagination metadata (total_count, next_cursor) so agents can iterate through large result sets.
• Ensure response objects include chaining IDs. E.g., get_next_task should return { task: { id, title, ... }, project_id } so an immediate call to start_task(task.id) succeeds without a lookup.

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

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