---
name: claude-settings-optimizer
description: |
  Diagnose all Claude Desktop errors and optimize context usage.
  Covers 8 error categories: context limits, output interruption,
  length/file errors, usage limits, server capacity, MCP connection,
  account issues, and output quality problems.
  Triggers: settings audit, exceed response limit, MCP error, token error.
---

# Claude Desktop Settings Checker

Diagnose Claude Desktop errors and optimize context usage.

## Error Quick Reference

| Error Type | Message Pattern | Category |
|------------|-----------------|----------|
| Context too large | "Exceed response limit" | Input |
| Output interrupted | "Response could not be fully generated" | Output |
| Length exceeded | "Message will exceed the length limit" | Input |
| Conversation limit | "This conversation reached its maximum length" | Input |
| File too large | "Files larger than 10mb" / "X% over the length limit" | File |
| Rate limited | "5-hour limit reached" / "X messages left" | Usage |
| Server overload | "Due to unexpected capacity constraints" | Server |
| MCP failure | "Error connecting to [ServerName]" | MCP |
| Account issue | "Account has been disabled" | Account |

## Quick Diagnosis Tree

```
Error occurred?
│
├─ BEFORE response started?
│   ├─ "Exceed response limit" → Reduce input context
│   ├─ "Length limit" → Break into smaller messages
│   ├─ "File too large" → Reduce file size or excerpt
│   ├─ "Capacity constraints" → Wait and retry
│   └─ "MCP error" → Check MCP configuration
│
├─ DURING response?
│   ├─ "Could not be fully generated" → Request smaller output
│   └─ Output suddenly stopped → Retry or chunk request
│
└─ BEFORE even sending?
    ├─ "5-hour limit reached" → Wait for reset
    ├─ "Messages left" → Near usage limit
    └─ "Account disabled" → Contact support
```

## Understanding Token Limits

| Model | Context Window | Output Limit | Practical Available |
|-------|---------------|--------------|---------------------|
| Claude 3.5 Sonnet | 200K tokens | ~8K tokens | ~150K after system |
| Claude 3 Opus | 200K tokens | ~4K tokens | ~150K after system |
| Claude 3 Haiku | 200K tokens | ~4K tokens | ~160K after system |

---

# CATEGORY 1: Input/Context Errors

## Error: "Exceed response limit"

**Causes:**
1. Loaded context too large (MCP tools + skills + files)
2. Conversation history accumulated
3. Multiple large files attached

## Quick Diagnosis

When user reports "Exceed response limit":

### Step 1: Check Loaded Context

Ask user to share their `claude_desktop_config.json`:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Analyze:
- [ ] Number of MCP servers configured
- [ ] Servers with many tools (>20 tools each)
- [ ] Missing or poor `serverInstructions`

### Step 2: Estimate Token Usage

| Component | Tokens (approx) | Notes |
|-----------|-----------------|-------|
| Per MCP server | 500-2,000 | Base overhead |
| Per tool definition | 100-500 | Depends on schema complexity |
| Playwright MCP | ~13,500 | 20+ tools, detailed schemas |
| Notion MCP | ~5,000 | Moderate |
| GitHub MCP | ~18,000 | Many tools |
| Custom SKILL.md | 200-2,000 | Depends on length |
| Attached file | Variable | ~4 tokens per word |

**Red flags:**
- More than 5 MCP servers active
- Any server without `serverInstructions`
- Total MCP tools > 100

### Step 3: Review Loaded Skills

Check for:
- Skills with long SKILL.md files (>1,000 words)
- Multiple skills loaded simultaneously
- Skills with embedded reference data

## Optimization Recommendations

### MCP Server Optimization

**Priority 1: Add serverInstructions**

Every MCP server needs concise instructions:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "...",
      "serverInstructions": "Browser automation for web testing. Use for: screenshots, page analysis, form testing. Keywords: browser, DOM, screenshot"
    }
  }
}
```

Pattern: `[Purpose]. Use for: [case1], [case2]. Keywords: [kw1], [kw2]`

**Priority 2: Reduce Active Servers**

Keep only essential servers active. Disable or remove:
- Servers used less than weekly
- Servers with overlapping functionality
- Servers with 30+ tools (like Zapier)

### Conversation Management

**Before complex tasks:**
1. Start fresh conversation for unrelated work
2. Avoid attaching multiple large files
3. Request concise outputs

**During long sessions:**
1. Start new conversation at natural breakpoints
2. Summarize important context before continuing
3. Remove completed file attachments

### Project File Optimization

For project skills and configurations:

| File Type | Target Length | Max |
|-----------|--------------|-----|
| SKILL.md | 500 words | 1,000 words |
| Project instructions | 200 words | 500 words |
| Embedded data | 0 | Move to external |

**Optimization techniques:**
1. Move reference data to separate files (load on demand)
2. Use tables instead of prose
3. Remove redundant information
4. Link to documentation instead of embedding

## Token Budget Calculator

Help user calculate their baseline:

```
System overhead:        ~10,000 tokens (fixed)
MCP servers:            [count] × ~3,000 = [estimate]
Loaded skills:          [count] × ~500 = [estimate]
Project instructions:   ~[estimate based on length]
────────────────────────────────────────────────
Baseline total:         [sum]
Available for work:     200,000 - [sum] = [remaining]
Available percentage:   [remaining/200,000 × 100]%
```

**Targets:**
- Baseline: < 40,000 tokens (20%)
- Available: > 160,000 tokens (80%)

**Warning zone:**
- Baseline > 60,000 tokens: Likely to hit limits
- Available < 140,000 tokens: Reduce configuration

## Output Format

After diagnosis, provide:

```markdown
## Settings Check Report

### Configuration Summary
- MCP Servers: [count] ([tokens estimate])
- Active Skills: [count] ([tokens estimate])
- Baseline Total: ~[X] tokens ([Y]%)
- Available: ~[Z] tokens ([W]%)

### Issues Found
1. [Critical]: [issue description]
2. [Warning]: [issue description]

### Recommended Actions
1. [Action with specific steps]
2. [Action with specific steps]

### Quick Wins (immediate impact)
- [ ] [Specific change]
- [ ] [Specific change]
```

## Common Scenarios

### Scenario: Too Many MCP Servers

**Symptoms:** Errors on first message of conversation
**Solution:** Disable non-essential servers, add serverInstructions

### Scenario: Long Conversation History

**Symptoms:** Errors after many exchanges
**Solution:** Start new conversation, summarize context

### Scenario: Large File Attachments

**Symptoms:** Errors when attaching files
**Solution:** Attach smaller excerpts, use file references

### Scenario: Complex Skill Loaded

**Symptoms:** Errors when using specific skill
**Solution:** Refactor skill, move data to references

---

## Error 2: "Response could not be fully generated"

This error occurs when **output generation** is interrupted mid-stream.

### Causes

| Cause | Description | Frequency |
|-------|-------------|-----------|
| **Output token limit** | Response exceeded ~4K-8K output limit | Common |
| **Safety filter** | Content flagged during generation | Occasional |
| **Network interruption** | Connection dropped mid-stream | Occasional |
| **Server timeout** | Generation took too long | Rare |
| **Rate limiting** | Too many requests in short time | Rare |

### Common Triggers

**1. Requesting too much output:**
```
❌ "Write a complete 50-page report on..."
❌ "Generate the entire application code"
❌ "List all 500 items with full descriptions"

✅ "Write section 1: introduction and overview"
✅ "Generate the authentication module first"
✅ "List items 1-50 with descriptions"
```

**2. Vague prompts (produce longer responses):**
```
❌ "Explain everything about machine learning"
✅ "Explain gradient descent in 3 paragraphs"
```

**3. Code generation without scope:**
```
❌ "Build me a full-stack e-commerce site"
✅ "Create the product listing component with pagination"
```

### Solutions

| Situation | Fix |
|-----------|-----|
| Long report/document | Request section by section |
| Large codebase | Generate module by module |
| Comprehensive list | Paginate (1-50, 51-100, etc.) |
| Detailed explanation | Ask for "brief" or "concise" version |
| Transient failure | Simply retry the request |

### Prompting Techniques

**Add output constraints:**
- "In under 500 words..."
- "Provide a concise summary..."
- "List the top 10..."
- "Focus only on..."

**Chunk large tasks:**
- "First, outline the structure"
- "Now write section 1"
- "Continue with section 2"

**Request format control:**
- "Use bullet points, not paragraphs"
- "Provide a table summary"
- "Give me just the key points"

### When to Retry vs. Rephrase

| Scenario | Action |
|----------|--------|
| Error on first attempt | Retry once |
| Error persists after retry | Rephrase with smaller scope |
| Error always at same point | Content may be triggering filter |
| Error after long generation | Request was too ambitious |

---

# CATEGORY 3: Length & File Errors

## Error: "Your message will exceed the length limit"

**Full message:** "Your message will exceed the length limit for this chat..."

**Causes:**
- Single message too long (approaching context limit)
- Too much text pasted at once

**Solutions:**
1. Break content into smaller chunks
2. Summarize key sections before sending
3. Ask Claude to identify relevant portions first
4. Start a new conversation

## Error: "This conversation reached its maximum length"

**Cause:** Accumulated conversation history filled context window

**Solutions:**
1. Start a new conversation
2. Copy essential context to new chat
3. Use shorter exchanges going forward

## Error: "Message is X% over the length limit"

**Full message:** "Message is X% over the length limit. Try replacing the attached file with smaller excerpts."

**Cause:** Attached file(s) too large for remaining context

**Solutions:**
1. Extract relevant excerpts only
2. Summarize large documents before attaching
3. Split across multiple messages
4. Use file references instead of full content

## Error: "You may not upload files larger than 10MB"

**Cause:** Single file exceeds 10MB limit

**Solutions:**
1. Compress file if possible
2. Split into smaller files
3. Extract text content only
4. Use external link and describe content

---

# CATEGORY 4: Usage & Rate Limit Errors

## Error: "5-hour limit reached - resets [time]"

**Cause:** Hit plan's usage cap within 5-hour window

**Solutions:**
1. Wait until reset time shown
2. Upgrade plan for higher limits
3. Optimize prompts to use fewer tokens

## Error: "Approaching 5-hour limit"

**Cause:** Warning before hitting limit

**Solutions:**
1. Prioritize remaining important tasks
2. Use concise prompts
3. Avoid exploratory conversations

## Error: "X messages left until [time]"

**Cause:** Near message limit (free tier)

**Solutions:**
1. Combine multiple questions into one
2. Wait for reset
3. Consider paid plan

## Error: "5-hour limit resets [time] - continuing with extra usage"

**Note:** This is informational for paid plans with extra usage enabled
**Action:** Extra usage automatically continues; monitor costs

---

# CATEGORY 5: Server & Capacity Errors

## Error: "Due to unexpected capacity constraints, Claude is unable to respond"

**Cause:** High system-wide demand

**Solutions:**
1. Wait 2-5 minutes and retry
2. Try during off-peak hours
3. Check [status.claude.com](https://status.claude.com) for incidents

## HTTP Error Codes

| Code | Meaning | Solution |
|------|---------|----------|
| 500 | Internal Server Error | Wait and retry |
| 429 | Too Many Requests | Slow down, wait |
| 403 | Forbidden | Check account status |
| 400 | Bad Request | Check input format |

## Error: "Claude AI Saving Chat Failed"

**Cause:** Issue saving conversation to servers

**Solutions:**
1. Refresh the page
2. Check internet connection
3. Copy important content locally
4. Try again later

---

# CATEGORY 6: MCP Connection Errors

## Error: "There was an error connecting to [ServerName]"

**Causes:**
1. Server not running
2. Incorrect configuration
3. Transport type mismatch (stdio vs HTTP)
4. Authentication failure

### Diagnosis Steps

**Step 1: Check server logs**
- macOS: `~/Library/Logs/Claude/mcp-server-SERVERNAME.log`
- Windows: `%APPDATA%\Claude\logs\mcp-server-SERVERNAME.log`

**Step 2: Verify configuration**
```bash
# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows PowerShell
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"
```

**Step 3: Test server independently**
```bash
# Test if server starts
npx @anthropic-ai/mcp-server-name
```

### Common MCP Issues

| Issue | Symptom | Fix |
|-------|---------|-----|
| Transport mismatch | HTTP server with stdio config | Add `"transport": "http"` |
| Path with spaces | Server fails on Windows | Use escaped paths or `%APPDATA%` |
| Missing env vars | Auth failures | Add to `"env"` in config |
| Server not installed | "command not found" | Run `npm install -g` first |
| Port conflict | Server won't start | Change port or kill existing |

### After Config Changes

**Critical:** Completely quit and restart Claude Desktop after any config changes.

## Error: "Required parameter" validation errors

**Cause:** MCP tool schema mismatch (regression bug)

**Solutions:**
1. Update Claude Desktop to latest version
2. Check MCP server for updates
3. Temporarily disable problematic server

---

# CATEGORY 7: Account Errors

## Error: "Your account has been disabled"

**Full message:** "Your account has been disabled after an automatic review of your recent activities."

**Cause:** Automated system flagged account

**Solutions:**
1. Contact Anthropic support
2. Review Terms of Service
3. Do not create new accounts (may worsen situation)

## Error: "This organization has been disabled"

**Cause:** Organization-level suspension

**Solution:** Organization admin must contact Anthropic

## Error: "There was an error logging you in"

**Causes:**
- VPN interference
- Browser extensions blocking
- Cached credentials issue

**Solutions:**
1. Disable VPN
2. Disable browser extensions temporarily
3. Clear browser cache and cookies
4. Try incognito/private window
5. Check [status.claude.com](https://status.claude.com)

## Error: "Error Sending Codes - Check Your Phone Number"

**Cause:** Phone verification failed during signup

**Solutions:**
1. Verify correct country code
2. Check all digits entered correctly
3. Try different phone number
4. Wait and retry later

---

# CATEGORY 8: Output Quality Issues

## Issue: Output Suddenly Stops (Cutoff)

**Symptoms:** Response ends mid-sentence or mid-code

**Causes:**
1. Hit output token limit (~4K-8K)
2. Safety filter triggered
3. Server timeout

**Solutions:**
1. Ask "Please continue from where you stopped"
2. Request smaller chunks upfront
3. Be more specific in scope

## Issue: Gibberish or Nonsensical Output

**Symptoms:** Incoherent text, random characters

**Causes:**
1. Model confusion from complex prompt
2. Conflicting instructions
3. Edge case in training

**Solutions:**
1. Simplify prompt
2. Start new conversation
3. Rephrase request differently

## Issue: Mixed Languages or Character Issues

**Symptoms:** Unexpected language switches, formatting problems

**Causes:**
1. Ambiguous language context
2. Copy-pasted special characters

**Solutions:**
1. Explicitly state desired language
2. Clean input text of special characters
3. Add "Please respond in [language]"

## Issue: Claude Refuses to Respond

**Symptoms:** Declines request citing policy

**Causes:**
1. Request triggered safety guidelines
2. Ambiguous phrasing interpreted as harmful

**Solutions:**
1. Rephrase more clearly
2. Explain legitimate use case
3. Break into smaller, clearer requests

---

## Prevention Checklist

### Context/Input Errors

- [ ] Maximum 5 MCP servers active
- [ ] All servers have serverInstructions
- [ ] Skills under 1,000 words
- [ ] Start fresh conversations for new topics
- [ ] Avoid attaching files over 50KB (prefer excerpts)
- [ ] Individual files under 10MB

### Output Errors

- [ ] Break large requests into chunks
- [ ] Use specific scope in prompts
- [ ] Request concise/brief outputs when possible
- [ ] Paginate lists and tables (50 items max)
- [ ] Generate code module by module
- [ ] Retry once before rephrasing

### Usage Limits

- [ ] Monitor "messages left" warnings
- [ ] Combine related questions into single prompts
- [ ] Use concise prompts to conserve tokens
- [ ] Know your plan's reset schedule

### MCP Stability

- [ ] Test MCP servers independently before adding
- [ ] Keep server logs accessible for debugging
- [ ] Restart Claude Desktop after config changes
- [ ] Update MCP servers regularly
- [ ] Document working configurations

### General Best Practices

- [ ] Check [status.claude.com](https://status.claude.com) when experiencing issues
- [ ] Keep Claude Desktop updated
- [ ] Clear browser cache periodically (web version)
- [ ] Disable VPN if experiencing login issues
- [ ] Back up important conversations locally
