pact-mcp provides 5 tools with reasonable naming (verb_noun pattern) and basic descriptions. However, critical gaps undermine production readiness: parameter descriptions are sparse or missing entirely, output schemas are not documented, and error handling lacks recovery guidance. The pact_scaffold tool accepts complex nested objects without clear validation rules. pact_run is a WRITE operation but lacks confirmation/dry-run patterns. Most tools describe WHAT they do but not WHEN to use them or what the LLM should expect in responses. Average description length ~120 chars (below 194-char baseline). No tool annotations (readOnlyHint/destructiveHint) despite clear risk classifications.

• Document output schemas for all tools. E.g., pact_check returns {status: 'OK'|'ERROR', errors?: [{line, col, message}]}. pact_list returns {declarations: [{type, name, signature}]}. This enables LLMs to chain tools and extract required fields.
• Add parameter descriptions for 'source' (e.g., 'Raw .pact source code as a string, not a file path') and 'flow' (e.g., 'Name of a flow declared in the source. Call pact_list first to discover available flows.').
• Add tool annotations to the MCP tool registration: readOnlyHint=true for pact_check/pact_list/pact_validate_permissions; destructiveHint=true for pact_run/pact_scaffold (they modify state or generate code).
• For pact_scaffold, document the agents array schema with examples: agents[].tools should be a list of tool names (strings); agents[].permissions should be a list of permission strings (e.g., 'read:file', 'write:network'). Provide an example agent definition.
• Add error recovery guidance. E.g., pact_check should return 'Syntax error at line 5: unexpected token. Check for missing semicolons or mismatched braces.' instead of raw parse errors. pact_run should return 'Flow not found: did you mean one of: [flow_a, flow_b]?'