feat: schema default flip, repair tickets, and hallucination reduction

- Flip include_schemas default to true in list_tools handler
- Add structured repair_ticket in data on ARG_VALIDATION_FAILED
- Add fuzzy matching (normalization + Levenshtein) for did_you_mean
- Add circuit breaker (3-tier escalation) for repeated failures
- Parse Ajv errors into categories: missing_required, type_errors,
  enum_violations, format_errors, unknown_fields from strippedArgs
- Update stale guidance text in getHelp, useTool, server, docs
- 11 new repair ticket tests (60 total passing)

Author: harryblam

docs/ERROR_CODES_REFERENCE.md

@@ -115,16 +115,41 @@ The arguments provided to a tool don't match its expected JSON schema.
 - Fields exceeding length limits
 
 **Solutions:**
-1. Run `list_tools(package_id: "...", include_schemas: true)` to see full schema
-2. Ensure all required fields are present
-3. Check that types match exactly (strings, numbers, booleans)
-4. Use `dry_run: true` with `use_tool` to validate before executing
+1. Inspect `data.repair_ticket` in the error response for surgical fix guidance:
+   - `missing_required`
+   - `type_errors`
+   - `enum_violations`
+   - `format_errors`
+   - `unknown_fields` + `did_you_mean`
+   - `schema_fragments` (field-level snippets; escalates to full schema on repeated failures)
+2. Fix only the fields listed in the repair ticket and retry
+3. Use `dry_run: true` with `use_tool` to validate arguments before execution
+4. If `repair_ticket.attempt >= 3`, ask the user for clarification before retrying
 
 **Related get_help:** `get_help(error_code: -32003)`
 
 **Example log message:**
 ```
-Argument validation failed for tool 'write_file': missing required property 'content'
+Argument validation failed for tool 'write_file'. Missing required: content. Type errors: overwrite (expected boolean, got string).
+```
+
+**Example error data payload:**
+```json
+{
+  "repair_ticket": {
+    "missing_required": ["content"],
+    "type_errors": [{"field": "overwrite", "expected": "boolean", "got": "string", "value": "yes"}],
+    "enum_violations": [],
+    "format_errors": [],
+    "unknown_fields": ["filePath"],
+    "did_you_mean": {"filePath": "path"},
+    "schema_fragments": {
+      "content": {"type": "string"},
+      "path": {"type": "string"}
+    },
+    "attempt": 1
+  }
+}
 ```
 
 ---

src/handlers/getHelp.ts

@@ -135,7 +135,7 @@ Returns:
 
 ## Tips
 - Start with summarize: true for readable format
-- Use include_schemas: true only when debugging
+- Schemas are included by default; set include_schemas: false for lighter responses
 - Page through results if a package has many tools`,
 
     error_handling: `# Error Handling in Super-MCP
@@ -285,7 +285,7 @@ The tool_id doesn't exist in the specified package.
 The arguments provided don't match the tool's expected schema.
 
 ## How to Fix
-1. Run \`list_tools(package_id: "...", include_schemas: true)\`
+1. Run \`list_tools(package_id: "...")\`
 2. Review the exact schema requirements
 3. Ensure all required fields are present
 4. Check that types match exactly (string vs number)
@@ -437,7 +437,7 @@ use_tool(
 
 ## Troubleshooting
 - If tools aren't working, check \`health_check_all()\`
-- For detailed schemas: \`list_tools(package_id: "${packageId}", include_schemas: true)\`
+- Schemas are included by default: \`list_tools(package_id: "${packageId}")\`
 - Test arguments: Add \`dry_run: true\` to use_tool`;
 
   } catch (error) {

src/handlers/listTools.ts

@@ -11,7 +11,7 @@ export async function handleListTools(
     package_id,
     name_pattern,
     summarize = true,
-    include_schemas = false,
+    include_schemas = true,
     page_size = 20,
     page_token,
   } = input;