Shipwright MCP exposes 9 task-management tools with complete JSON schemas and basic descriptions. All tools have input schemas with type definitions and examples. However, descriptions are minimal (10-30 chars), parameter descriptions are absent or generic, and output schemas are not documented. Error handling guidance is missing. The server follows verb_noun naming (tasks_list, tasks_create) but lacks LLM-optimized descriptions that explain WHEN to use each tool and what to expect. No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels (READ_ONLY, WRITE, DESTRUCTIVE). Parameter constraints are present (enums for 'state', 'kind', 'ready', 'hitl') but lack inline descriptions explaining their meaning.

• Expand all tool descriptions to 50-200 characters. Example: 'tasks_list' → 'List tasks filtered by status, state, repo, assignee, or session. Returns paginated results with task IDs, titles, and metadata. Use this to discover available tasks before claiming or updating.'
• Add descriptions to every parameter. For 'state' enum, write: 'Task state: open (not started), in_progress (active), ready (awaiting claim), blocked (dependency issue), closed (completed).' For 'limit', write: 'Max results per page (1-100, default 20).'
• Document output schemas for each tool. Example for tasks_list: 'Returns {tasks: [{id, title, status, state, repo, assignee, claimedBy, updatedAt}], total, nextOffset}.'
• Add tool annotations: readOnlyHint=true for tasks_list/tasks_get/tasks_distinct; destructiveHint=true for tasks_delete; idempotentHint=true for tasks_heartbeat (safe to retry).
• For tasks_update, define the updateable fields in the schema (e.g., status, assignee, priority, description) and document which combinations are valid. For tasks_delete, add a 'confirm' parameter or return a confirmation token to prevent accidental deletion.