[Docs] Main SKILL.md lacks custom-tool fallback — agents misdiagnose "Unknown tool" as missing tool / server failure

[Docs] Main SKILL.md lacks custom-tool fallback — agents misdiagnose "Unknown tool" as missing tool / server failure

Summary

The bundled unity-mcp-skill documents custom tools only in references/tools-reference.md (§ Custom Tools). The main SKILL.md "Quick Start: Resource-First Workflow" — the part agents actually follow — never mentions that a project can register custom tools which are not in the client's direct tool list and not callable by name.

What happened in practice

While working in a project that registers project-specific custom tools, an agent needed one of them. It was not in the direct tool list, so the agent — following SKILL.md — concluded the tool did not exist and started troubleshooting the infrastructure instead:

• toggling tool group switches via manage_tools
• recompiling scripts, restarting the editor
• re-verifying transport / instance selection

Several wasted rounds later, the actual fix turned out to be two steps:

1. Read the mcpforunity://custom-tools resource → confirm the tool is registered
2. Invoke it via execute_custom_tool { tool_name, parameters }

Key facts that were only discoverable in a reference file:

• Custom tools are not callable by name; the only entry point is execute_custom_tool.
• An "Unknown tool" error does not mean the tool is missing. Diagnosis order should be:
  1. tools/list — see what is actually registered in this session
  2. mcpforunity://custom-tools — check project-registered custom tools
  3. manage_tools group switches — the tool may be hidden by group visibility
  4. only then conclude the tool is truly absent

(Note: this is a documentation gap, distinct from #837, where custom tools genuinely fail under stdio transport.)

Suggested fix

Add a short fallback note to the main SKILL.md Quick Start, right after step 3 ("Find what you need"), e.g.:

Step 3 fallback — project custom tools. If the tool you need is not in your direct tool list, the project may register custom tools. Discover them via mcpforunity://custom-tools; they are not callable by name — invoke them via execute_custom_tool { tool_name, parameters }. If a call returns "Unknown tool": first run tools/list to see what is actually registered, then check group switches via manage_tools; only after both fail consider the tool truly missing.

Why the main file, not just references

Reference files are consulted only after a failure. A discovery-order rule must live where the agent looks first — otherwise every agent working on a project with custom tools repeats the exact failure mode above.

Environment

• MCP for Unity package 9.6.0 (skill unchanged on latest main, v10.2.0)
• Unity 2022.3, HTTP transport, Claude Code / ZCode clients