TOOL_DOCSTRING_MIGRATION.mdā¢8.12 kB
# Tool Docstring Migration Guide
**Status:** In Progress
**Standard:** [TOOL_DOCSTRING_STANDARD.md](./TOOL_DOCSTRING_STANDARD.md)
**Started:** October 10, 2025
---
## Migration Status
### Completed ā
- [x] query_tools.py - execute_query (reference implementation)
### In Progress š
- [ ] query_tools.py - quick_data_sample
- [ ] query_tools.py - export_query_results
### Pending š
**Connection Tools** (connection_tools.py) - 5 tools
- [ ] list_supported_databases
- [ ] register_database_connection
- [ ] list_database_connections
- [ ] test_database_connection
- [ ] test_all_database_connections
**Schema Tools** (schema_tools.py) - 4 tools
- [ ] list_databases
- [ ] list_tables
- [ ] describe_table
- [ ] get_schema_diff
**Data Tools** (data_tools.py)
- [ ] All tools need review
**FTS Tools** (fts_tools.py)
- [ ] All tools need review
**Management Tools** (management_tools.py)
- [ ] All tools need review
**Registry Tools** (registry_tools.py)
- [ ] All tools need review
**Windows Tools** (windows_tools.py)
- [ ] All tools need review
**Calibre Tools** (calibre_tools.py)
- [ ] All tools need review
**Media/Plex Tools** (media_tools.py, plex_tools.py)
- [ ] All tools need review
**Firefox Tools** (firefox/*.py) - ~15 files
- [ ] All tools need review
**Help Tools** (help_tools.py)
- [ ] help
- [ ] tool_help
**Init Tools** (init_tools.py)
- [ ] init_database
---
## Migration Steps
### For Each Tool:
1. **Review Current Docstring**
- Identify what's missing
- Check for triple quotes inside docstring
- Note any technical debt
2. **Update Following Standard**
```python
'''Brief description.
Detailed description...
Parameters:
param1: Description
- Details
param2: Description (default: value)
- Details
Returns:
Dictionary containing:
- key1: Description
- key2: Description
Usage:
When to use...
Common scenarios:
- Scenario 1
- Scenario 2
Examples:
Basic usage:
code
# Returns: output
Advanced usage:
code
# Returns: output
Error handling:
code
# Returns: error output
Raises:
Exception: When...
Notes:
- Note 1
- Note 2
See Also:
- related_tool: Description
'''
```
3. **Test**
- Verify no syntax errors
- Check docstring renders correctly
- Validate examples are accurate
4. **Update This File**
- Move tool from Pending to Completed
- Add any notes about special cases
---
## Common Issues and Solutions
### Issue 1: Triple Quotes in Examples
**Problem:**
```python
def tool():
"""
Examples:
query = """SELECT * FROM table""" # BREAKS!
"""
```
**Solution:**
```python
def tool():
'''
Examples:
query = "SELECT * FROM table" # Use single-line string
# Or describe the string instead of showing it
'''
```
### Issue 2: Missing Parameters
**Problem:**
```python
def tool(param1, param2):
"""Does stuff.""" # No parameter docs!
```
**Solution:**
```python
def tool(param1, param2):
'''Does specific stuff.
Parameters:
param1: First parameter description
- Details about param1
param2: Second parameter description
- Details about param2
'''
```
### Issue 3: No Examples
**Problem:**
```python
def tool():
"""Returns data.""" # How do I use it?
```
**Solution:**
```python
def tool():
'''Returns data from database.
Examples:
Basic usage:
result = await tool()
# Returns: {'success': True, 'data': [...]}
Error case:
result = await tool()
if not result['success']:
print(result['error'])
'''
```
---
## Batch Update Script
Use this Python script to check tool docstrings:
```python
#!/usr/bin/env python3
'''Check tool docstrings for compliance with standard.'''
import ast
import os
import re
from pathlib import Path
def check_docstring(func_name, docstring):
'''Check if docstring meets standard.'''
issues = []
if not docstring:
issues.append("Missing docstring")
return issues
# Check for required sections
required_sections = ['Parameters:', 'Returns:', 'Usage:', 'Examples:']
for section in required_sections:
if section not in docstring:
issues.append(f"Missing {section} section")
# Check for triple quotes inside
if '"""' in docstring and docstring.count('"""') > 2:
issues.append("Contains triple quotes inside docstring")
# Check for examples with output
if 'Examples:' in docstring:
example_section = docstring.split('Examples:')[1]
if '# Returns:' not in example_section and '#' not in example_section:
issues.append("Examples missing expected output comments")
return issues
def scan_tool_file(filepath):
'''Scan a Python file for tool docstrings.'''
with open(filepath, 'r', encoding='utf-8') as f:
content = f.read()
tree = ast.parse(content)
results = []
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef):
# Check if it has @mcp.tool() decorator
has_mcp_tool = any(
isinstance(d, ast.Call) and
hasattr(d.func, 'attr') and
d.func.attr == 'tool'
for d in node.decorator_list
)
if has_mcp_tool:
docstring = ast.get_docstring(node)
issues = check_docstring(node.name, docstring)
if issues:
results.append({
'function': node.name,
'line': node.lineno,
'issues': issues
})
return results
def main():
'''Main entry point.'''
tools_dir = Path('src/database_operations_mcp/tools')
all_issues = {}
for py_file in tools_dir.rglob('*.py'):
if py_file.name.startswith('_'):
continue
issues = scan_tool_file(py_file)
if issues:
all_issues[str(py_file)] = issues
# Print report
if all_issues:
print("Tool Docstring Issues Found:\n")
for filepath, issues in all_issues.items():
print(f"š {filepath}")
for issue in issues:
print(f" ā ļø {issue['function']} (line {issue['line']})")
for problem in issue['issues']:
print(f" - {problem}")
print()
else:
print("ā
All tool docstrings are compliant!")
if __name__ == '__main__':
main()
```
**Usage:**
```bash
cd /path/to/database-operations-mcp
python check_docstrings.py
```
---
## Priority Order
Update in this order for maximum impact:
1. **High Priority** - Most used tools
- execute_query ā
- register_database_connection
- list_tables
- describe_table
- list_database_connections
2. **Medium Priority** - Frequently used
- test_database_connection
- quick_data_sample
- export_query_results
- list_databases
3. **Low Priority** - Specialized tools
- Windows registry tools
- Media/Plex tools
- Firefox bookmark tools
- Calibre tools
---
## Notes
- Use single quotes (') for docstrings to avoid conflicts
- Keep examples realistic and runnable
- Show both success and error cases
- Document all parameters, even obvious ones
- Link related tools in See Also section
---
## Completion Checklist
Before marking migration complete:
- [ ] All tools have compliant docstrings
- [ ] No triple quotes inside docstrings
- [ ] All examples include expected output
- [ ] Validation script passes
- [ ] Documentation updated
- [ ] Tests updated if needed
---
*Migration Guide v1.0.0*
*Part of MCPB Documentation*
*Location: `mcpb/docs/TOOL_DOCSTRING_MIGRATION.md`*