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?'
This commit is contained in:
YueGuobin 2026-06-07 00:32:39 +08:00
parent 1f985a2823
commit 012df5af57
No known key found for this signature in database
2 changed files with 44 additions and 0 deletions

View File

@ -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

View File

@ -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