@@ -148,9 +148,16 @@ def check_skills():
                 errors.append(f"{rel}: frontmatter missing {field}")
         if "globs" in fields and parse_globs(fields["globs"]) is None:
             errors.append(f"{rel}: globs must be a JSON-style list of strings")
+        if not fields.get("description", "").startswith("Use when"):
+            errors.append(f"{rel}: description should start with 'Use when' and name what the user asks or sees")
         if len(body) < 100:
             errors.append(f"{rel}: body too short ({len(body)} chars, minimum 100)")
-    print(f"Checked {len(dirs)} skills")
+    skill_text = "".join(read(f"skills/{d.name}/SKILL.md") for d in dirs if (d / "SKILL.md").exists())
+    tools = re.findall(r"^@mcp\.tool\(\)\s+def (\w+)", read("mcp-server/server.py"), re.MULTILINE)
+    for tool in tools:
+        if f"`{tool}`" not in skill_text:
+            errors.append(f"MCP tool {tool} is not mentioned by any skill; tell the agent when to call it")
+    print(f"Checked {len(dirs)} skills and {len(tools)} MCP tool references")
     return errors
 
 
 
@@ -1,6 +1,6 @@
 ---
 title: Addressables and Asset Management
-description: Managing assets with the Addressables system for async loading, memory management, and remote content delivery.
+description: Use when loading assets at runtime, replacing Resources.Load, shrinking build size, fixing memory that never frees after scene changes, or shipping DLC and remote content. Covers Addressables async loading, handles and Release, labels, groups, and remote catalogs.
 globs: ["**/*.cs", "**/AddressableAssetsData/**"]
 standards-version: 1.10.0
 ---
 
@@ -1,12 +1,16 @@
 ---
 title: Animation Systems
-description: Unity animation workflows including Animator Controller, Timeline, DOTween, and sprite animation for 2D.
+description: Use when the user works on character or UI animation, Animator Controllers, blend trees, state transitions, root motion, Timeline cutscenes, tweens, or 2D sprite animation. Covers Animator parameters and hashing, Timeline, DOTween, and sprite animation.
 globs: ["**/*.cs", "**/*.controller", "**/*.anim", "**/*.playable"]
 standards-version: 1.10.0
 ---
 
 # Animation Systems
 
+## MCP Tools
+
+Call `lookup_api` with `category` set to `animation` to check Animator and Timeline APIs. If the tools are unavailable, continue without them.
+
 ## Animator Controller
 
 The Animator Controller is Unity's primary animation state machine. It manages states, transitions, parameters, layers, and blend trees.
 
@@ -1,12 +1,16 @@
 ---
 title: Audio Systems
-description: Audio implementation patterns including AudioSource, AudioMixer, spatial audio, and audio management.
+description: Use when the user adds sound effects or music, hears clipping or missing sounds, needs volume sliders, 3D positional audio, or an audio manager. Covers AudioSource, AudioMixer groups and exposed parameters, spatial audio, pooling, and audio import settings.
 globs: ["**/*.cs", "**/*.mixer"]
 standards-version: 1.10.0
 ---
 
 # Audio Systems
 
+## MCP Tools
+
+Call `lookup_api` with `category` set to `audio` to check AudioSource and AudioMixer APIs. If the tools are unavailable, continue without them.
+
 ## Core Components
 
 ### AudioSource
 
@@ -1,6 +1,6 @@
 ---
 title: ECS and DOTS
-description: Entity Component System development with Unity Entities, Jobs, and Burst for high-performance simulation.
+description: Use when the user works with DOTS, ECS, Entities, ISystem or SystemBase, IComponentData, Bakers, SubScenes, the Job System, or Burst, or needs to simulate thousands of objects. Covers entity queries, baking, entity command buffers, jobs, and Burst constraints.
 globs: ["**/*.cs"]
 standards-version: 1.10.0
 ---
 
@@ -1,12 +1,16 @@
 ---
 title: Editor Scripting
-description: Extending the Unity Editor with custom inspectors, editor windows, property drawers, gizmos, and Scene View overlays using UI Toolkit.
+description: Use when the user wants to extend the Unity Editor with a custom inspector, editor window, property drawer, menu item, gizmo, Scene View overlay, or tooling under an Editor folder. Covers UI Toolkit inspectors, SerializedProperty, Undo, and editor-only assemblies.
 globs: ["**/Editor/**/*.cs"]
 standards-version: 1.10.0
 ---
 
 # Editor Scripting
 
+## MCP Tools
+
+Call `scaffold_script` with `type` set to `editor-window`, `custom-inspector`, or `property-drawer` to generate editor code that already lives in an Editor folder. Use `lookup_api` with `category` set to `editor` to check editor APIs. If the tools are unavailable, continue without them.
+
 ## Overview
 
 All editor scripts must be placed in an `Editor/` folder (or reference an Editor-only assembly definition). Code in Editor folders is excluded from player builds.
 
@@ -1,6 +1,6 @@
 ---
 title: Input Systems
-description: Input handling with the New Input System package and legacy Input Manager migration guidance.
+description: Use when the user handles keyboard, mouse, gamepad, or touch input, sees errors from UnityEngine.Input, sets up PlayerInput or .inputactions assets, adds key rebinding, or adds local multiplayer. Covers the Input System package, action maps, callbacks, rebinding, and migrating from the legacy Input Manager.
 globs: ["**/*.cs", "**/*.inputactions"]
 standards-version: 1.10.0
 ---
 
@@ -1,12 +1,16 @@
 ---
 title: MonoBehaviour Patterns
-description: Comprehensive guide to MonoBehaviour lifecycle, async patterns with Awaitable, and common Unity design patterns.
+description: Use when the user writes or debugs MonoBehaviour scripts, asks about Awake vs Start vs OnEnable, execution order, coroutines vs async, Awaitable, singletons, events, or object pooling. Covers lifecycle order, Awaitable async patterns, and common gameplay architecture patterns.
 globs: ["**/*.cs"]
 standards-version: 1.10.0
 ---
 
 # MonoBehaviour Patterns
 
+## MCP Tools
+
+Call `scaffold_script` with `type` set to `monobehaviour`, `state-machine`, or `interface` to generate a new script in the project's namespace, and `lookup_api` to check a Unity API and see deprecation warnings before suggesting it. If the tools are unavailable, continue without them.
+
 ## Lifecycle Execution Order
 
 Unity calls MonoBehaviour methods in a strict order each frame:
 
@@ -1,12 +1,16 @@
 ---
 title: Multiplayer Networking
-description: Multiplayer networking patterns with Netcode for GameObjects, Netcode for Entities, Mirror, and Photon Fusion.
+description: Use when the user builds multiplayer, sets up a host or server, syncs state, writes RPCs or NetworkVariables, or chooses between Netcode for GameObjects, Netcode for Entities, Mirror, and Photon Fusion. Covers authority, ownership, RPCs, prediction, and solution tradeoffs.
 globs: ["**/*.cs"]
 standards-version: 1.10.0
 ---
 
 # Multiplayer Networking
 
+## MCP Tools
+
+Call `analyze_project` to see which networking package and version the project has installed before writing netcode, and `lookup_api` with `category` set to `networking` to check APIs. If the tools are unavailable, continue without them.
+
 ## Choosing a Solution
 
 Pick based on your game's scale and genre:
 
@@ -1,12 +1,16 @@
 ---
 title: Performance Optimization
-description: Unity-specific performance best practices for CPU, GPU, memory, and profiling tools.
+description: Use when the game lags, stutters, drops FPS, has GC spikes, too many draw calls, long load times, or high memory use, or the user asks how to profile. Covers CPU and GC allocations, pooling, batching and the SRP Batcher, LOD and culling, memory, and the Profiler, Memory Profiler, and Frame Debugger.
 globs: ["**/*.cs"]
 standards-version: 1.10.0
 ---
 
 # Performance Optimization
 
+## MCP Tools
+
+Call `lookup_api` before recommending an API; it flags deprecated or slow patterns (for example `FindObjectOfType`) and names the replacement. Call `analyze_project` to check the render pipeline and scripting backend before giving GPU or IL2CPP advice. If the tools are unavailable, continue without them.
+
 ## CPU Optimization
 
 ### Cache Component References