Improve MCP Tool Usability with Discovery Helpers and Better Documentation

[StatPan]

Summary

Improve MCP tool usability by adding discovery helpers, better documentation, and simplified search interfaces. Current tools require users to know specific Korean terms, valid values, and Assembly structure details, making them difficult to use without prior knowledge.

Problem Statement

After testing the get_bill_info tool, several usability issues were identified:

1. No discoverability: Users don't know valid values for proc_status, age, committee names, etc.
2. Lack of examples: Hard to understand what parameters like bill_id should look like
3. Complex parameters: Date format (YYYYMMDD) and Korean terminology are not intuitive
4. No guidance: Users need domain knowledge of Korean National Assembly structure
5. Limited feedback: Return types don't provide context about total results or search scope

Proposed Solutions

1. Add Discovery/Helper Tools 🔍

Create new MCP tools to help users discover valid values:

@mcp.tool()
async def get_assembly_terms() -> list[dict]:
    """
    Get list of National Assembly terms with date ranges.
    
    Returns:
        List of assembly terms with age number, start/end dates, and current status.
        Example: [{"age": "22", "start": "2024-05-30", "end": "2028-05-29", "current": true}, ...]
    """

@mcp.tool()
async def get_bill_statuses() -> list[dict]:
    """
    Get list of valid bill processing statuses.
    
    Returns:
        List of status codes with Korean and English descriptions.
        Example: [{"code": "위원회심사", "name_kr": "위원회 심사", "name_en": "Committee Review"}, ...]
    """

@mcp.tool()
async def get_committees() -> list[dict]:
    """
    Get list of National Assembly committees.
    
    Returns:
        List of committees with names in Korean and English.
        Example: [{"name_kr": "기획재정위원회", "name_en": "Strategy and Finance Committee"}, ...]
    """

2. Improve Tool Documentation 📚

Enhance existing tool docstrings with:

• Concrete examples of common use cases
• List of frequently used values (e.g., common proc_status values)
• Clear explanation of current assembly term
• Korean-English glossary for key terms

Example enhancement for get_bill_info:

"""
Search for legislative bills (의안) by ID, name, proposal date, or processing status.

Examples:
    - Get recent bills: age="22", limit=10
    - Search by name: age="22", bill_name="예산", limit=5
    - Filter by status: age="21", proc_status="위원회심사"
    - Specific date: age="21", propose_dt="20200530"

Common proc_status values:
    - "접수" (Received)
    - "위원회심사" (Committee Review)
    - "본회의" (Plenary Session)
    - "가결" (Passed)
    - "부결" (Rejected)

Args:
    age: Assembly term (대수). Use "22" for current term (2024-2028)
    bill_id: Unique bill identifier (의안ID)
    bill_name: Bill name in Korean (의안명) - partial match supported
    propose_dt: Proposal date in YYYYMMDD format (제안일자)
    proc_status: Processing status (처리상태) - see common values above
    limit: Maximum number of results (1-100, default: 10)

Returns:
    List of Bill objects with details including proposer, status, dates, and link
"""

3. Add MCP Resources 📋

Expose static reference data as MCP resources:

@mcp.resource("assembly://terms")
async def assembly_terms_resource():
    """Provides list of assembly terms as a resource"""

@mcp.resource("assembly://statuses")
async def bill_statuses_resource():
    """Provides list of valid bill processing statuses"""

@mcp.resource("assembly://committees")
async def committees_resource():
    """Provides list of National Assembly committees"""

@mcp.resource("assembly://glossary")
async def glossary_resource():
    """Provides Korean-English glossary of common terms"""

4. Create Simplified Search Tool 🔎

Add a user-friendly wrapper for common search patterns:

@mcp.tool()
async def search_bills_simple(
    query: str,
    assembly_term: str = "22",
    max_results: int = 10
) -> dict:
    """
    Simple bill search - just provide keywords.
    
    Searches across bill names and automatically uses the current assembly term.
    
    Args:
        query: Search keywords in Korean (e.g., "예산", "세법개정")
        assembly_term: Assembly term to search (default: "22" - current term)
        max_results: Maximum results to return (1-100, default: 10)
    
    Returns:
        Dictionary with search metadata and results:
        {
            "query": "예산",
            "assembly_term": "22",
            "total_found": 150,
            "returned": 10,
            "bills": [Bill, Bill, ...]
        }
    
    Examples:
        - search_bills_simple("예산")
        - search_bills_simple("세법", assembly_term="21", max_results=5)
    """

5. Enhance Return Types 📊

Modify return types to provide more context:

# Instead of: list[Bill]
# Return: dict with metadata

{
    "query_params": {...},
    "total_found": 150,
    "returned": 10,
    "has_more": true,
    "bills": [Bill, Bill, ...]
}

Implementation Plan

Phase 1: Core Discovery Tools

• Implement get_assembly_terms() with hardcoded data for terms 20-22
• Implement get_bill_statuses() with common status codes
• Implement get_committees() with major committees
• Add unit tests for new tools

Phase 2: Documentation Enhancement

• Update get_bill_info docstring with examples and common values
• Update list_api_services docstring with examples
• Update call_api_raw docstring with examples
• Create Korean-English glossary

Phase 3: Resources

• Add MCP resources for static reference data
• Test resource access from MCP clients

Phase 4: Simplified Interface

• Implement search_bills_simple() wrapper
• Enhance return types with metadata
• Add integration tests

Phase 5: Documentation

• Update README with usage examples
• Create docs/TOOLS.md with comprehensive tool documentation
• Add common use case examples

Success Criteria

• Users can discover valid parameter values without external documentation
• Tool docstrings provide enough context for first-time users
• Simple search works with just keywords (no need to know Assembly structure)
• All new tools have >80% test coverage
• Documentation includes at least 5 common use case examples

Related Issues

• Documentation & Examples #22 (Documentation & Examples)
• [EPIC] Implement 7 Core MCP Tools for National Assembly Data #11 (Initial MCP implementation)

Labels

enhancement, documentation

Priority

High - This directly impacts user experience and adoption of the MCP server