From 012df5af57d4b3f1d429589429160b36a947f8df Mon Sep 17 00:00:00 2001
From: YueGuobin <yueguobin@outlook.com>
Date: Sun, 7 Jun 2026 00:32:39 +0800
Subject: [PATCH] docs: add simplified MCP tool description guide to project
 memory

Added a focused, concise memory document about MCP tool description
location. Simplified from 180 lines to 45 lines to capture only the
essential information needed for future conversations.

Key points documented:
- MCP tool descriptions are defined in @mcp.tool() functions in __init__.py
- NOT in *_TOOLS arrays in individual module files
- Must restart GNS3 server to see description updates
- Description requirements: explicit formats, ranges, and examples

This replaces the verbose 180-line version with a practical 45-line
guide focused on answering: 'Where should I write tool descriptions so
the AI can see them?'
---
 .claude/memory/MEMORY.md                     |  1 +
 .claude/memory/mcp-tool-description-guide.md | 43 ++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 .claude/memory/mcp-tool-description-guide.md

diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md
index e02b12fbc..59456d279 100644
--- a/.claude/memory/MEMORY.md
+++ b/.claude/memory/MEMORY.md
@@ -30,3 +30,4 @@
 
 ### MCP Service
 - **[MCP Service Design](./mcp-service-design.md)** - MCP (Model Context Protocol) service architecture using FastMCP with SSE transport, JWT auth, 29 tools across 5 domains
+- **[MCP Tool Description Location](./mcp-tool-description-guide.md)** - Where to define MCP tool descriptions: in `@mcp.tool()` functions in `__init__.py`, not in `*_TOOLS` arrays
diff --git a/.claude/memory/mcp-tool-description-guide.md b/.claude/memory/mcp-tool-description-guide.md
new file mode 100644
index 000000000..ca4ebcf42
--- /dev/null
+++ b/.claude/memory/mcp-tool-description-guide.md
@@ -0,0 +1,43 @@
+---
+name: mcp-tool-description-location
+description: Where to define MCP tool descriptions so AI can see them
+metadata:
+  type: reference
+---
+
+# MCP Tool Description Location
+
+## Key Point
+MCP tool descriptions are defined in `@mcp.tool()` decorator functions in `__init__.py`, NOT in the `*_TOOLS` arrays in individual module files.
+
+## Correct Location
+**File**: `gns3server/api/routes/mcp/__init__.py`
+
+**Example**:
+```python
+@mcp.tool()
+async def update_link(
+    project_id: Annotated[str, Field(description="UUID of the project")],
+    link_id: Annotated[str, Field(description="UUID of the link to update")],
+    **kwargs: Any,
+) -> list[dict[str, Any]]:
+    """Update a link's properties.
+    
+    Put detailed descriptions here, especially for complex parameters.
+    Include format requirements, ranges, and examples.
+    """
+    # implementation
+```
+
+## Wrong Location
+- ❌ `LINK_TOOLS` in `gns3server/api/routes/mcp/links.py`
+- ❌ `TEMPLATE_TOOLS` in `gns3server/api/routes/mcp/templates.py`
+
+## Activation
+**Must restart GNS3 server** for description updates to take effect.
+
+## Description Requirements
+- Be explicit about data formats (arrays vs single values)
+- Include parameter ranges and constraints
+- Provide usage examples
+- Prevent common errors in the description itself