Menu
Generate professional documentation for MCP tools including docstrings, examples, and API reference
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | mcp-documentation |
| description | Generate professional documentation for MCP tools including docstrings, examples, and API reference |
The MCP Documentation Skill generates comprehensive, professional documentation for Model Context Protocol tools. It creates docstrings, usage examples, API references, and integration guides that help users and agents understand tool capabilities.
Request: "Document the get_current_weather tool"
[Provide tool code]
Skill: Generates comprehensive documentation
Output: Enhanced docstring + README section + API ref
Request: "Create API documentation for all weather tools"
[Provide multiple tools]
Skill: Generates cross-tool API reference
Output: Complete API.md file with all tools documented
@mcp.tool()
async def tool_name(param1: str, param2: int = 10) -> dict:
"""
[One-liner: What the tool does in one clear sentence]
[Detailed description explaining the tool's purpose,
when to use it, and what problems it solves]
Args:
param1: [Description of param1]
[Valid values, ranges, constraints]
Example: "London", "Tokyo"
(required)
param2: [Description of param2]
[Valid values, ranges]
(default: 10)
Returns:
Dictionary with fields:
- field1 (type): Description of field1
- field2 (type): Description of field2
- field3 (type): Description of field3
Example return:
{
"field1": "example_value",
"field2": 123,
"field3": 45.6
}
Example usage:
result = await tool_name("London", param2=20)
if "error" in result:
print(f"Error: {result['error']}")
else:
print(f"Success: {result['field1']}")
"""
❌ Bad: "Gets information about something"
✓ Good: "Get current weather conditions for any geographic coordinates"
"""
Explains:
- What the tool does
- When to use it (use cases)
- What problems it solves
- Any limitations or caveats
- How it relates to other tools
"""
"""
Args:
latitude: Geographic latitude in degrees (-90 to 90)
Example: 51.5 (London)
(required)
units: Temperature scale - "metric" or "imperial"
(default: "metric")
"""
"""
Returns:
Dictionary with weather data:
- temperature (float): Current temperature in specified units
- condition (str): Main weather condition (Sunny, Cloudy, etc.)
- humidity (int): Relative humidity percentage (0-100)
- wind_speed (float): Wind speed in specified units
- timestamp (int): Unix timestamp of observation
"""
"""
Example:
Get weather for London in Celsius:
>>> result = await get_current_weather(lat=51.5, lon=-0.1, units="metric")
>>> print(result["temperature"]) # 15.2
>>> print(result["condition"]) # Cloudy
"""
## get_current_weather
Get current weather conditions for any geographic coordinates.
### Quick Start
```bash
# Ask Copilot or call directly
result = await get_current_weather(lat=51.5, lon=-0.1, units="metric")
```
{
"temperature": 15.2,
"feels_like": 14.8,
"condition": "Cloudy",
"humidity": 72,
"pressure": 1013,
"wind_speed": 3.5,
"units": "metric"
}
Invalid latitude returns:
{
"error": "Latitude must be between -90 and 90",
"provided": 95
}
## API Reference Format
```markdown
# Weather & Mapping API Reference
## Tools
### get_current_weather
| Attribute | Value |
|-----------|-------|
| **Name** | get_current_weather |
| **Type** | Retrieval |
| **Purpose** | Get current weather for coordinates |
| **Async** | Yes |
### Parameters
| Name | Type | Required | Range | Default | Description |
|------|------|----------|-------|---------|-------------|
| lat | float | Yes | -90 to 90 | N/A | Latitude coordinate |
| lon | float | Yes | -180 to 180 | N/A | Longitude coordinate |
| units | string | No | metric, imperial | metric | Temperature units |
### Response
| Field | Type | Description | Example |
|-------|------|-------------|---------|
| temperature | float | Current temperature | 15.2 |
| condition | string | Main weather | "Cloudy" |
| humidity | int | Relative humidity % | 72 |
| wind_speed | float | Wind speed | 3.5 |
| units | string | Units used | "metric" |
### Error Codes
| Code | HTTP | Meaning |
|------|------|---------|
| INVALID_COORDS | 400 | Latitude or longitude out of range |
| TIMEOUT | 504 | API request timed out |
| API_ERROR | 502 | Weather API returned error |
| UNKNOWN_ERROR | 500 | Unexpected error occurred |
{
"location": "London, England, United Kingdom",
"temperature": 15.2,
"feels_like": 14.8,
"condition": "Cloudy",
"description": "overcast clouds",
"humidity": 72,
"pressure": 1013,
"wind_speed": 3.5,
"units": "metric"
}
{
"error": "Latitude must be between -90 and 90",
"code": "INVALID_COORDS",
"provided": 95
}
❌ Bad: "Retrieves meteorological data"
✓ Good: "Get current weather conditions (temperature, humidity, wind, etc.)"
❌ Bad: "Accepts a location name"
✓ Good: "Accepts a location name (e.g., 'London', 'New York', 'Eiffel Tower')"
❌ Bad: "Takes a number"
✓ Good: "Takes a latitude number between -90 (South Pole) and 90 (North Pole)"
❌ Bad: "Returns weather data"
✓ Good:
{
"temperature": 15.2,
"condition": "Cloudy",
"humidity": 72
}
❌ Bad: "May return an error"
✓ Good: "Returns error if latitude < -90 or > 90: {'error': 'Invalid latitude', 'code': 'INVALID_COORDS'}"
result = await get_current_weather(lat=51.5, lon=-0.1)
result = await get_current_weather(lat=51.5, lon=-0.1, units="imperial")
result = await get_current_weather(lat=51.5, lon=-0.1)
if "error" in result:
print(f"Failed: {result['error']}")
else:
print(f"Temperature: {result['temperature']}°C")
# First, search for location
locations = await search_location("London")
loc = locations[0]
# Then, get weather for it
weather = await get_current_weather(lat=loc["latitude"], lon=loc["longitude"])
/document-mcp-tool to refresh documentationQ: How detailed should docstrings be? A: Complete enough that an agent can understand the tool without seeing code. Include Args, Returns, and at least one example.
Q: Should I document every possible error? A: Document error conditions your tool can produce. Common ones: parameter validation errors, API failures, timeouts.
Q: How many examples do I need? A: At minimum one per tool. Ideally: basic usage, with optional params, error handling, and integration examples.
Q: Who reads this documentation? A: Three audiences: agents (to understand tool), developers (to integrate), and API consumers (to use).
Perform comprehensive code review of MCP tools focusing on security, reliability, and best practices
Plan and execute MCP server deployment to production environments
Generate and manage comprehensive test suites for MCP tools with coverage reporting