Overview
Most SchemaWP issues fall into three categories: tools not loading, conflicting instructions, or the agent not understanding a domain. This page helps you identify which one you’re dealing with.
Ask the Agent Directly
The agent can explain its own reasoning. If something looks wrong, ask:
- “Why did you do X?”
- “What skills do you have loaded?”
- “What tools are available to you?”
The agent will list its active tools, loaded skills, and explain the decisions it made. This is usually the fastest diagnostic step.
Tools Not Loading
If tools are missing or new tools aren’t appearing after connecting an MCP server, this is almost always a caching issue — not a plugin or server problem.
Fix:
- Go to Claude Settings → Capabilities
- Set Tool access mode to Tools already loaded
- Restart Claude
In other clients (Cursor, Windsurf, etc.), look for an equivalent “reload MCP” or “reconnect server” option.
If tools still don’t appear after a restart, try reconnecting the MCP server.
Conflicting Instructions
SchemaWP agents operate under several instruction layers:
- Claude root-level custom instructions (your Claude profile)
- Skill files loaded per domain (colors, spacing, typography, etc.)
- Site context from the live WordPress installation
These can conflict. Ask the agent which instructions it’s following and where they came from — it will identify the source and surface the conflict.
Site context and skill instructions take precedence for domain-specific decisions. Root-level instructions govern general behavior. If a conflict is causing bad output, update site context via SchemaWP settings.
Missing ACSS Context
If the agent makes incorrect ACSS decisions — wrong token names, skipping validation, misreading a color scale — it may lack domain context. The agent has a dedicated tool to pull ACSS documentation for any feature.
Prompt it directly:
- “Load the ACSS docs for [feature].”
- “What does ACSS say about fluid typography?”
The agent will fetch the relevant reference and correct its approach.
Quick Diagnostic Checklist
| Symptom | Likely Cause | Fix |
|---|---|---|
| Tools missing after connecting MCP | Agent cache | Restart Claude, set “Tools already loaded” |
| Agent ignores a skill | Conflicting root instruction | Ask agent to explain; update site context |
| Wrong ACSS token used | Missing domain context | Ask agent to load ACSS docs for that feature |
| Patch applied without confirmation | Instruction layer conflict | Check root instructions vs. site context rules |
| New MCP tools not appearing | Stale connection | Reconnect MCP via troubleshooting guide |