REFACTORING_COMPLETE.md

@@ -1,311 +0,0 @@
-# MCP Tool Parameter Refactoring - COMPLETE
-
-## Executive Summary
-
-All 9 MCP tool definitions in `/home/rpm/claude/mcrentcast/src/mcrentcast/server.py` have been successfully refactored to use individual function parameters instead of Pydantic model classes.
-
-**Status:** ✅ COMPLETE
-**Date:** 2025-11-14
-**Commit:** 12dc79f
-**Files Changed:** 1 source file + 2 documentation files
-
----
-
-## Refactored Tools
-
-### Core Tools (9 Total)
-
-1. **set_api_key** (Line 177)
-   - Before: `set_api_key(request: SetApiKeyRequest)`
-   - After: `set_api_key(api_key: str)`
-   - Status: ✅ Refactored
-
-2. **search_properties** (Line 202)
-   - Status: ✅ Already refactored (reference implementation)
-
-3. **get_property** (Line 300)
-   - Before: `get_property(request: PropertyByIdRequest)`
-   - After: `get_property(property_id: str, force_refresh: bool = False)`
-   - Status: ✅ Refactored
-
-4. **get_value_estimate** (Line 363)
-   - Before: `get_value_estimate(request: ValueEstimateRequest)`
-   - After: `get_value_estimate(address: str, force_refresh: bool = False)`
-   - Status: ✅ Refactored
-
-5. **get_rent_estimate** (Line 426)
-   - Before: `get_rent_estimate(request: RentEstimateRequest)`
-   - After: `get_rent_estimate(address, propertyType, bedrooms, bathrooms, squareFootage, force_refresh)`
-   - Status: ✅ Refactored
-
-6. **search_sale_listings** (Line 510)
-   - Before: `search_sale_listings(request: ListingSearchRequest)`
-   - After: `search_sale_listings(address, city, state, zipCode, limit, offset, force_refresh)`
-   - Status: ✅ Refactored
-
-7. **search_rental_listings** (Line 593)
-   - Before: `search_rental_listings(request: ListingSearchRequest)`
-   - After: `search_rental_listings(address, city, state, zipCode, limit, offset, force_refresh)`
-   - Status: ✅ Refactored
-
-8. **get_market_statistics** (Line 676)
-   - Before: `get_market_statistics(request: MarketStatsRequest)`
-   - After: `get_market_statistics(city, state, zipCode, force_refresh)`
-   - Status: ✅ Refactored
-
-9. **expire_cache** (Line 752)
-   - Before: `expire_cache(request: ExpireCacheRequest)`
-   - After: `expire_cache(cache_key, endpoint, all)`
-   - Status: ✅ Refactored
-
-10. **set_api_limits** (Line 830)
-    - Before: `set_api_limits(request: SetLimitsRequest)`
-    - After: `set_api_limits(daily_limit, monthly_limit, requests_per_minute)`
-    - Status: ✅ Refactored
-
-### Additional Tools (Not Modified)
-
-- **get_cache_stats** (Line 794) - Already uses no parameters
-- **get_usage_stats** (Line 812) - Already uses individual parameters
-- **get_api_limits** (Line 873) - Already uses no parameters
-
----
-
-## Refactoring Pattern
-
-All refactored tools now follow this consistent pattern:
-
-```python
-@app.tool()
-async def tool_name(
-    param1: Type1,
-    param2: Optional[Type2] = default_value,
-    ...
-) -> Dict[str, Any]:
-    """Tool description.
-
-    Args:
-        param1: Parameter description
-        param2: Parameter description
-        ...
-    """
-    # Function implementation
-    # Uses parameters directly (no request.field references)
-    pass
-```
-
-### Key Changes Applied to Each Tool
-
-1. ✅ Removed Pydantic model class from parameter signature
-2. ✅ Expanded to individual typed parameters with proper defaults
-3. ✅ Updated all internal references from `request.field` to `field`
-4. ✅ For tools using `model_dump()`, manually built parameter dicts
-5. ✅ Added comprehensive docstrings with Args sections
-6. ✅ Verified function logic remains unchanged
-
----
-
-## Code Quality Metrics
-
-| Metric | Result |
-|--------|--------|
-| Python Syntax Check | ✅ PASSED |
-| No Pydantic Models in Signatures | ✅ VERIFIED |
-| All Docstrings Complete | ✅ VERIFIED |
-| Type Annotations Present | ✅ VERIFIED |
-| Default Values Preserved | ✅ VERIFIED |
-| No Breaking Changes | ✅ VERIFIED |
-| Function Logic Unchanged | ✅ VERIFIED |
-
----
-
-## Technical Details
-
-### Parameters Refactored
-
-**Total individual parameters added:** 35
-
-**Breakdown by tool:**
-- set_api_key: 1 parameter
-- get_property: 2 parameters
-- get_value_estimate: 2 parameters
-- get_rent_estimate: 6 parameters
-- search_sale_listings: 7 parameters
-- search_rental_listings: 7 parameters
-- get_market_statistics: 4 parameters
-- expire_cache: 3 parameters
-- set_api_limits: 3 parameters
-
-### Lines of Code Changed
-
-- Total source file modifications: 350+ lines
-- New documentation files: 2 (REFACTORING_SUMMARY.md, TOOLS_REFACTORING_CHECKLIST.md)
-- Preserved functionality: 100%
-
----
-
-## Benefits Achieved
-
-### 1. FastMCP Protocol Compatibility
-Individual parameters are the recommended approach in FastMCP 2.x+, ensuring proper JSON-RPC parameter mapping and validation.
-
-### 2. Improved Type Safety
-Explicit parameter types in function signatures provide better IDE support and catch errors at definition time.
-
-### 3. Better Error Handling
-No need to validate or extract fields from request objects during execution.
-
-### 4. Enhanced Readability
-Function signatures clearly show all available parameters and their types without requiring model class inspection.
-
-### 5. Simplified Client Usage
-MCP clients can pass parameters directly without constructing request objects.
-
-### 6. Standards Compliance
-Follows FastMCP guidelines documented at https://gofastmcp.com/servers/tools
-
----
-
-## Documentation Created
-
-### 1. REFACTORING_SUMMARY.md
-Comprehensive before/after comparison for each of the 9 refactored tools, including:
-- Code snippets showing exact changes
-- Line-by-line parameter mappings
-- Benefits and rationale
-- Status of unused Pydantic models
-
-### 2. TOOLS_REFACTORING_CHECKLIST.md
-Detailed verification checklist including:
-- Tool-by-tool refactoring status
-- Quality assurance checkpoints
-- Summary statistics
-- Recommendations for future work
-
-### 3. REFACTORING_COMPLETE.md (This Document)
-High-level overview and completion report.
-
----
-
-## Files Modified
-
-```
-src/mcrentcast/server.py
-  ├── Line 177: set_api_key refactored
-  ├── Line 300: get_property refactored
-  ├── Line 363: get_value_estimate refactored
-  ├── Line 426: get_rent_estimate refactored
-  ├── Line 510: search_sale_listings refactored
-  ├── Line 593: search_rental_listings refactored
-  ├── Line 676: get_market_statistics refactored
-  ├── Line 752: expire_cache refactored
-  └── Line 830: set_api_limits refactored
-
-REFACTORING_SUMMARY.md (new file)
-TOOLS_REFACTORING_CHECKLIST.md (new file)
-```
-
----
-
-## Git Commit Information
-
-**Commit Hash:** 12dc79f
-**Branch:** main
-**Author:** Refactoring Expert Agent
-**Date:** 2025-11-14
-
-**Commit Message:**
-```
-Refactor all MCP tool definitions to use individual parameters
-
-Replace Pydantic model classes with individual function parameters across all 9 tools...
-[Full message in git log]
-```
-
----
-
-## Verification Steps Performed
-
-1. ✅ Syntax validation with `python -m py_compile`
-2. ✅ Grep search for remaining Pydantic request models in tool signatures (none found)
-3. ✅ Manual inspection of all 9 refactored tools
-4. ✅ Verification of parameter defaults against original models
-5. ✅ Documentation review for completeness
-6. ✅ Git commit verification
-
----
-
-## What Remains (Optional Future Work)
-
-### Unused Pydantic Models
-The following request model classes (lines 58-123) are no longer used and can be safely removed:
-- SetApiKeyRequest
-- PropertyByIdRequest
-- ValueEstimateRequest
-- RentEstimateRequest
-- ListingSearchRequest
-- ListingByIdRequest (never used)
-- MarketStatsRequest
-- ExpireCacheRequest
-- SetLimitsRequest
-
-**Recommendation:** Keep for backward compatibility until confirming no external dependencies reference them.
-
-### Documentation Updates
-- Update API documentation if it references Pydantic request models
-- Update client library code if it constructs request objects
-- Consider adding migration guide for API consumers
-
----
-
-## Testing Recommendations
-
-### Unit Tests to Consider
-```python
-# Test that individual parameters are properly passed
-async def test_get_property_parameters():
-    result = await get_property(
-        property_id="test_123",
-        force_refresh=True
-    )
-    assert result is not None
-
-# Test optional parameters
-async def test_search_sale_listings_optional_params():
-    result = await search_sale_listings(
-        city="Austin",
-        state="TX"
-    )
-    assert result["success"] is True
-```
-
-### Integration Tests
-Verify MCP clients can properly call tools with individual parameters and that parameter validation works correctly.
-
----
-
-## Success Criteria Met
-
-- [x] All 9 tools refactored to individual parameters
-- [x] No Pydantic models used in @app.tool() signatures
-- [x] Type annotations properly applied
-- [x] Default values preserved from original models
-- [x] Docstrings added with Args sections
-- [x] Function logic unchanged (no breaking changes)
-- [x] Python syntax validated
-- [x] Changes committed to git
-- [x] Documentation created
-- [x] Code follows FastMCP best practices
-
----
-
-## Conclusion
-
-The refactoring of MCP tool definitions is complete and verified. All 9 tools now use individual parameters instead of Pydantic model classes, improving protocol compatibility, type safety, and code clarity. The changes maintain 100% backward functional compatibility while modernizing the codebase to follow FastMCP 2.x+ standards.
-
-**Status: READY FOR PRODUCTION**
-
----
-
-*For detailed information about each refactored tool, see REFACTORING_SUMMARY.md*
-*For verification checklist and QA details, see TOOLS_REFACTORING_CHECKLIST.md*

REFACTORING_QUICK_REFERENCE.md

@@ -1,250 +0,0 @@
-# MCP Tools Refactoring - Quick Reference Guide
-
-## What Was Changed
-
-All 9 MCP tool definitions in `src/mcrentcast/server.py` were refactored from using Pydantic request model classes to individual function parameters.
-
-## Tool Transformation Summary
-
-### Tool 1: set_api_key (Line 177)
-```diff
-- async def set_api_key(request: SetApiKeyRequest):
-+ async def set_api_key(api_key: str):
-```
-**Parameters:** 1 | **Request Model Removed:** SetApiKeyRequest
-
-### Tool 2: get_property (Line 300)
-```diff
-- async def get_property(request: PropertyByIdRequest):
-+ async def get_property(property_id: str, force_refresh: bool = False):
-```
-**Parameters:** 2 | **Request Model Removed:** PropertyByIdRequest
-
-### Tool 3: get_value_estimate (Line 363)
-```diff
-- async def get_value_estimate(request: ValueEstimateRequest):
-+ async def get_value_estimate(address: str, force_refresh: bool = False):
-```
-**Parameters:** 2 | **Request Model Removed:** ValueEstimateRequest
-
-### Tool 4: get_rent_estimate (Line 426)
-```diff
-- async def get_rent_estimate(request: RentEstimateRequest):
-+ async def get_rent_estimate(
-+     address: str,
-+     propertyType: Optional[str] = None,
-+     bedrooms: Optional[int] = None,
-+     bathrooms: Optional[float] = None,
-+     squareFootage: Optional[int] = None,
-+     force_refresh: bool = False
-+ ):
-```
-**Parameters:** 6 | **Request Model Removed:** RentEstimateRequest
-
-### Tool 5: search_sale_listings (Line 510)
-```diff
-- async def search_sale_listings(request: ListingSearchRequest):
-+ async def search_sale_listings(
-+     address: Optional[str] = None,
-+     city: Optional[str] = None,
-+     state: Optional[str] = None,
-+     zipCode: Optional[str] = None,
-+     limit: int = 10,
-+     offset: int = 0,
-+     force_refresh: bool = False
-+ ):
-```
-**Parameters:** 7 | **Request Model Removed:** ListingSearchRequest
-
-### Tool 6: search_rental_listings (Line 593)
-```diff
-- async def search_rental_listings(request: ListingSearchRequest):
-+ async def search_rental_listings(
-+     address: Optional[str] = None,
-+     city: Optional[str] = None,
-+     state: Optional[str] = None,
-+     zipCode: Optional[str] = None,
-+     limit: int = 10,
-+     offset: int = 0,
-+     force_refresh: bool = False
-+ ):
-```
-**Parameters:** 7 | **Request Model Removed:** ListingSearchRequest
-
-### Tool 7: get_market_statistics (Line 676)
-```diff
-- async def get_market_statistics(request: MarketStatsRequest):
-+ async def get_market_statistics(
-+     city: Optional[str] = None,
-+     state: Optional[str] = None,
-+     zipCode: Optional[str] = None,
-+     force_refresh: bool = False
-+ ):
-```
-**Parameters:** 4 | **Request Model Removed:** MarketStatsRequest
-
-### Tool 8: expire_cache (Line 752)
-```diff
-- async def expire_cache(request: ExpireCacheRequest):
-+ async def expire_cache(
-+     cache_key: Optional[str] = None,
-+     endpoint: Optional[str] = None,
-+     all: bool = False
-+ ):
-```
-**Parameters:** 3 | **Request Model Removed:** ExpireCacheRequest
-
-### Tool 9: set_api_limits (Line 830)
-```diff
-- async def set_api_limits(request: SetLimitsRequest):
-+ async def set_api_limits(
-+     daily_limit: Optional[int] = None,
-+     monthly_limit: Optional[int] = None,
-+     requests_per_minute: Optional[int] = None
-+ ):
-```
-**Parameters:** 3 | **Request Model Removed:** SetLimitsRequest
-
----
-
-## Statistics
-
-| Category | Count |
-|----------|-------|
-| Tools Refactored | 9 |
-| Total Parameters Added | 35 |
-| Request Models Removed | 9 |
-| Documentation Files | 3 |
-| Source Files Modified | 1 |
-| Breaking Changes | 0 |
-
----
-
-## Key Refactoring Pattern
-
-**Before (Using Pydantic Model):**
-```python
-@app.tool()
-async def some_tool(request: SomeRequest) -> Dict[str, Any]:
-    param1 = request.field1
-    param2 = request.field2
-    params = request.model_dump(exclude={"force_refresh"})
-```
-
-**After (Using Individual Parameters):**
-```python
-@app.tool()
-async def some_tool(
-    field1: str,
-    field2: Optional[int] = None,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Tool description.
-
-    Args:
-        field1: Description
-        field2: Description
-        force_refresh: Force cache refresh
-    """
-    param1 = field1
-    param2 = field2
-    params = {
-        "field1": field1,
-        "field2": field2
-    }
-```
-
----
-
-## Why This Matters
-
-### FastMCP Compatibility
-Individual parameters follow the recommended approach in FastMCP 2.x+, ensuring proper MCP protocol handling and parameter validation.
-
-### Type Safety
-Function signatures explicitly show all parameters and their types, providing better IDE support and catching errors earlier.
-
-### Code Clarity
-Parameters are visible at a glance without inspecting Pydantic model classes, reducing cognitive load.
-
-### Client Simplicity
-MCP clients can pass parameters directly without constructing request objects.
-
----
-
-## Documentation Files Created
-
-1. **REFACTORING_SUMMARY.md** - Detailed before/after analysis for each tool
-2. **TOOLS_REFACTORING_CHECKLIST.md** - QA verification and completion status
-3. **REFACTORING_COMPLETE.md** - Comprehensive completion report
-4. **REFACTORING_QUICK_REFERENCE.md** - This file
-
----
-
-## Commits Made
-
-1. **12dc79f**: Refactor all MCP tool definitions to use individual parameters
-2. **ab16a6f**: Add comprehensive refactoring completion report
-
----
-
-## Files Changed
-
-- `src/mcrentcast/server.py` - All 9 tool refactorings
-- `REFACTORING_SUMMARY.md` - New documentation
-- `TOOLS_REFACTORING_CHECKLIST.md` - New documentation
-- `REFACTORING_COMPLETE.md` - New documentation
-
----
-
-## Migration Guide for Users
-
-### If You Call These Tools Programmatically
-
-**Before:**
-```python
-from mcrentcast.server import get_property, PropertyByIdRequest
-
-result = await get_property(PropertyByIdRequest(
-    property_id="12345",
-    force_refresh=False
-))
-```
-
-**After:**
-```python
-from mcrentcast.server import get_property
-
-result = await get_property(
-    property_id="12345",
-    force_refresh=False
-)
-```
-
-### For MCP Client Integration
-
-The tools now accept parameters directly via the MCP protocol, simplifying client code and reducing overhead.
-
----
-
-## Verification Checklist
-
-- [x] All 9 tools refactored
-- [x] Type annotations in place
-- [x] Default values preserved
-- [x] Docstrings added/updated
-- [x] Python syntax validated
-- [x] No breaking changes to function behavior
-- [x] Git commits created
-- [x] Documentation complete
-
----
-
-## Status: COMPLETE
-
-All refactoring work is complete and verified. The code is ready for production use with improved FastMCP protocol compatibility and code clarity.
-
-For detailed information, see the other documentation files:
-- `REFACTORING_SUMMARY.md` - Detailed tool-by-tool analysis
-- `REFACTORING_COMPLETE.md` - Full completion report
-- `TOOLS_REFACTORING_CHECKLIST.md` - QA verification details

REFACTORING_SUMMARY.md

@@ -1,391 +0,0 @@
-# MCP Tool Parameter Refactoring Summary
-
-## Overview
-Successfully refactored all 9 MCP tool definitions in `/home/rpm/claude/mcrentcast/src/mcrentcast/server.py` to use individual function parameters instead of Pydantic model classes. This improves FastMCP protocol compatibility and simplifies parameter handling.
-
-## Refactoring Completed
-
-### 1. `set_api_key` (Lines 177-199)
-**Before:**
-```python
-async def set_api_key(request: SetApiKeyRequest) -> Dict[str, Any]:
-    settings.rentcast_api_key = request.api_key
-    # ... uses request.api_key
-```
-
-**After:**
-```python
-async def set_api_key(api_key: str) -> Dict[str, Any]:
-    """Set or update the Rentcast API key for this session.
-
-    Args:
-        api_key: Rentcast API key
-    """
-    settings.rentcast_api_key = api_key
-    # ... uses api_key directly
-```
-
-**Changes:**
-- Replaced `request: SetApiKeyRequest` parameter
-- All `request.api_key` references changed to `api_key`
-- Added comprehensive docstring with Args section
-
----
-
-### 2. `get_property` (Lines 296-356)
-**Before:**
-```python
-async def get_property(request: PropertyByIdRequest) -> Dict[str, Any]:
-    cache_key = client._create_cache_key(f"property-record/{request.property_id}", {})
-    # ... uses request.property_id and request.force_refresh
-```
-
-**After:**
-```python
-async def get_property(property_id: str, force_refresh: bool = False) -> Dict[str, Any]:
-    """Get detailed information for a specific property by ID.
-
-    Args:
-        property_id: Property ID from Rentcast
-        force_refresh: Force cache refresh
-    """
-    cache_key = client._create_cache_key(f"property-record/{property_id}", {})
-    # ... uses property_id and force_refresh directly
-```
-
-**Changes:**
-- Replaced `request: PropertyByIdRequest` with two individual parameters
-- All `request.property_id` changed to `property_id`
-- All `request.force_refresh` changed to `force_refresh`
-- Added proper docstring
-
----
-
-### 3. `get_value_estimate` (Lines 359-419)
-**Before:**
-```python
-async def get_value_estimate(request: ValueEstimateRequest) -> Dict[str, Any]:
-    cache_key = client._create_cache_key("value-estimate", {"address": request.address})
-    # ... uses request.address and request.force_refresh
-```
-
-**After:**
-```python
-async def get_value_estimate(address: str, force_refresh: bool = False) -> Dict[str, Any]:
-    """Get property value estimate for an address.
-
-    Args:
-        address: Property address
-        force_refresh: Force cache refresh
-    """
-    cache_key = client._create_cache_key("value-estimate", {"address": address})
-    # ... uses address and force_refresh directly
-```
-
-**Changes:**
-- Replaced `request: ValueEstimateRequest` with two individual parameters
-- All `request.address` changed to `address`
-- All `request.force_refresh` changed to `force_refresh`
-- Added proper docstring
-
----
-
-### 4. `get_rent_estimate` (Lines 422-503)
-**Before:**
-```python
-async def get_rent_estimate(request: RentEstimateRequest) -> Dict[str, Any]:
-    params = request.model_dump(exclude={"force_refresh"})
-    # ... uses request.address, request.propertyType, etc.
-```
-
-**After:**
-```python
-async def get_rent_estimate(
-    address: str,
-    propertyType: Optional[str] = None,
-    bedrooms: Optional[int] = None,
-    bathrooms: Optional[float] = None,
-    squareFootage: Optional[int] = None,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Get rent estimate for a property.
-
-    Args:
-        address: Property address
-        propertyType: Property type (Single Family, Condo, etc.)
-        bedrooms: Number of bedrooms
-        bathrooms: Number of bathrooms
-        squareFootage: Square footage
-        force_refresh: Force cache refresh
-    """
-    params = {
-        "address": address,
-        "propertyType": propertyType,
-        "bedrooms": bedrooms,
-        "bathrooms": bathrooms,
-        "squareFootage": squareFootage
-    }
-    # ... uses individual parameters directly
-```
-
-**Changes:**
-- Replaced `request: RentEstimateRequest` with 6 individual parameters
-- Removed `request.model_dump()` call, now builds params dict manually
-- All request field references changed to individual parameters
-- Added comprehensive docstring
-
----
-
-### 5. `search_sale_listings` (Lines 506-586)
-**Before:**
-```python
-async def search_sale_listings(request: ListingSearchRequest) -> Dict[str, Any]:
-    params = request.model_dump(exclude={"force_refresh"})
-    # ... uses request.address, request.city, etc.
-```
-
-**After:**
-```python
-async def search_sale_listings(
-    address: Optional[str] = None,
-    city: Optional[str] = None,
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    limit: int = 10,
-    offset: int = 0,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Search for properties for sale.
-
-    Args:
-        address: Property address
-        city: City name
-        state: State code
-        zipCode: ZIP code
-        limit: Max results (up to 500)
-        offset: Results offset for pagination
-        force_refresh: Force cache refresh
-    """
-    params = {
-        "address": address,
-        "city": city,
-        "state": state,
-        "zipCode": zipCode,
-        "limit": limit,
-        "offset": offset
-    }
-    # ... uses individual parameters directly
-```
-
-**Changes:**
-- Replaced `request: ListingSearchRequest` with 7 individual parameters
-- Removed `request.model_dump()`, now builds params dict manually
-- All request field references changed to individual parameters
-- Added comprehensive docstring
-
----
-
-### 6. `search_rental_listings` (Lines 589-669)
-**Before:**
-```python
-async def search_rental_listings(request: ListingSearchRequest) -> Dict[str, Any]:
-    params = request.model_dump(exclude={"force_refresh"})
-    # ... uses request.address, request.city, etc.
-```
-
-**After:**
-```python
-async def search_rental_listings(
-    address: Optional[str] = None,
-    city: Optional[str] = None,
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    limit: int = 10,
-    offset: int = 0,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Search for rental properties.
-
-    Args:
-        address: Property address
-        city: City name
-        state: State code
-        zipCode: ZIP code
-        limit: Max results (up to 500)
-        offset: Results offset for pagination
-        force_refresh: Force cache refresh
-    """
-    params = {
-        "address": address,
-        "city": city,
-        "state": state,
-        "zipCode": zipCode,
-        "limit": limit,
-        "offset": offset
-    }
-    # ... uses individual parameters directly
-```
-
-**Changes:**
-- Replaced `request: ListingSearchRequest` with 7 individual parameters
-- Removed `request.model_dump()`, now builds params dict manually
-- All request field references changed to individual parameters
-- Added comprehensive docstring
-
----
-
-### 7. `get_market_statistics` (Lines 672-745)
-**Before:**
-```python
-async def get_market_statistics(request: MarketStatsRequest) -> Dict[str, Any]:
-    params = request.model_dump(exclude={"force_refresh"})
-    # ... uses request.city, request.state, etc.
-```
-
-**After:**
-```python
-async def get_market_statistics(
-    city: Optional[str] = None,
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Get market statistics for a location.
-
-    Args:
-        city: City name
-        state: State code
-        zipCode: ZIP code
-        force_refresh: Force cache refresh
-    """
-    params = {
-        "city": city,
-        "state": state,
-        "zipCode": zipCode
-    }
-    # ... uses individual parameters directly
-```
-
-**Changes:**
-- Replaced `request: MarketStatsRequest` with 4 individual parameters
-- Removed `request.model_dump()`, now builds params dict manually
-- All request field references changed to individual parameters
-- Added comprehensive docstring
-
----
-
-### 8. `expire_cache` (Lines 748-787)
-**Before:**
-```python
-async def expire_cache(request: ExpireCacheRequest) -> Dict[str, Any]:
-    if request.all:
-        # ...
-    elif request.cache_key:
-        # ... uses request.cache_key
-```
-
-**After:**
-```python
-async def expire_cache(
-    cache_key: Optional[str] = None,
-    endpoint: Optional[str] = None,
-    all: bool = False
-) -> Dict[str, Any]:
-    """Expire cache entries to force fresh API calls.
-
-    Args:
-        cache_key: Specific cache key to expire
-        endpoint: Expire all cache for endpoint
-        all: Expire all cache entries
-    """
-    if all:
-        # ...
-    elif cache_key:
-        # ... uses cache_key directly
-```
-
-**Changes:**
-- Replaced `request: ExpireCacheRequest` with 3 individual parameters
-- All `request.all` changed to `all`
-- All `request.cache_key` changed to `cache_key`
-- All `request.endpoint` changed to `endpoint`
-- Added comprehensive docstring
-
----
-
-### 9. `set_api_limits` (Lines 826-866)
-**Before:**
-```python
-async def set_api_limits(request: SetLimitsRequest) -> Dict[str, Any]:
-    if request.daily_limit is not None:
-        # ... uses request.daily_limit, request.monthly_limit, etc.
-```
-
-**After:**
-```python
-async def set_api_limits(
-    daily_limit: Optional[int] = None,
-    monthly_limit: Optional[int] = None,
-    requests_per_minute: Optional[int] = None
-) -> Dict[str, Any]:
-    """Update API rate limits and usage quotas.
-
-    Args:
-        daily_limit: Daily API request limit
-        monthly_limit: Monthly API request limit
-        requests_per_minute: Requests per minute limit
-    """
-    if daily_limit is not None:
-        # ... uses daily_limit, monthly_limit, etc. directly
-```
-
-**Changes:**
-- Replaced `request: SetLimitsRequest` with 3 individual parameters
-- All `request.daily_limit` changed to `daily_limit`
-- All `request.monthly_limit` changed to `monthly_limit`
-- All `request.requests_per_minute` changed to `requests_per_minute`
-- Added comprehensive docstring
-
----
-
-## Benefits of This Refactoring
-
-1. **FastMCP Protocol Compatibility**: Individual parameters are the recommended approach for FastMCP tool definitions, ensuring proper MCP protocol handling
-
-2. **Improved Type Safety**: Parameters are explicitly typed, reducing the risk of type errors
-
-3. **Better Documentation**: Comprehensive docstrings with Args sections provide clear parameter descriptions
-
-4. **Simplified Error Handling**: No need to extract fields from request objects, reducing debugging complexity
-
-5. **Cleaner Code**: Direct parameter usage eliminates `request.field` chains throughout the functions
-
-6. **Consistency**: All tools now follow the same pattern (as demonstrated by the already-refactored `search_properties` tool)
-
-## Pydantic Models Status
-
-The following Pydantic request model classes are still defined but no longer used by the tools:
-- `SetApiKeyRequest` (line 58-60)
-- `PropertyByIdRequest` (line 72-75)
-- `ValueEstimateRequest` (line 77-80)
-- `RentEstimateRequest` (line 82-88)
-- `ListingSearchRequest` (line 91-98)
-- `ListingByIdRequest` (line 101-104) - never used
-- `MarketStatsRequest` (line 106-111)
-- `ExpireCacheRequest` (line 113-117)
-- `SetLimitsRequest` (line 119-123)
-
-These can be removed in a future cleanup refactoring if they're not needed elsewhere in the codebase.
-
-## Testing & Verification
-
-- Python syntax check: PASSED
-- All 9 tools successfully refactored
-- Implementation pattern matches the reference `search_properties` tool
-- No breaking changes to tool functionality or return types
-
-## File Changed
-
-**Path:** `/home/rpm/claude/mcrentcast/src/mcrentcast/server.py`
-
-Total lines modified: 350+ (across all 9 tool definitions and helper functions)

TOOLS_REFACTORING_CHECKLIST.md

@@ -1,203 +0,0 @@
-# MCP Tools Refactoring Checklist
-
-## All 9 Tools Successfully Refactored
-
-### Refactoring Pattern Reference
-All tools now follow the pattern established by `search_properties`:
-
-```python
-@app.tool()
-async def tool_name(
-    param1: type1,
-    param2: Optional[type2] = None,
-    ...
-) -> Dict[str, Any]:
-    """Tool description.
-
-    Args:
-        param1: Description
-        param2: Description
-        ...
-    """
-    # Function implementation with individual parameters
-    # No request.field references
-```
-
----
-
-## Tool-by-Tool Checklist
-
-### 1. set_api_key
-- [x] Removed `request: SetApiKeyRequest`
-- [x] Added individual `api_key: str` parameter
-- [x] Updated all references from `request.api_key` to `api_key`
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 2. get_property
-- [x] Removed `request: PropertyByIdRequest`
-- [x] Added individual parameters: `property_id: str`, `force_refresh: bool = False`
-- [x] Updated all `request.property_id` to `property_id`
-- [x] Updated all `request.force_refresh` to `force_refresh`
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 3. get_value_estimate
-- [x] Removed `request: ValueEstimateRequest`
-- [x] Added individual parameters: `address: str`, `force_refresh: bool = False`
-- [x] Updated all `request.address` to `address`
-- [x] Updated all `request.force_refresh` to `force_refresh`
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 4. get_rent_estimate
-- [x] Removed `request: RentEstimateRequest`
-- [x] Added 6 individual parameters:
-  - `address: str`
-  - `propertyType: Optional[str] = None`
-  - `bedrooms: Optional[int] = None`
-  - `bathrooms: Optional[float] = None`
-  - `squareFootage: Optional[int] = None`
-  - `force_refresh: bool = False`
-- [x] Removed `request.model_dump()` call
-- [x] Manually built params dict from individual parameters
-- [x] Updated all request field references to individual parameters
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 5. search_sale_listings
-- [x] Removed `request: ListingSearchRequest`
-- [x] Added 7 individual parameters:
-  - `address: Optional[str] = None`
-  - `city: Optional[str] = None`
-  - `state: Optional[str] = None`
-  - `zipCode: Optional[str] = None`
-  - `limit: int = 10`
-  - `offset: int = 0`
-  - `force_refresh: bool = False`
-- [x] Removed `request.model_dump()` call
-- [x] Manually built params dict from individual parameters
-- [x] Updated all request field references to individual parameters
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 6. search_rental_listings
-- [x] Removed `request: ListingSearchRequest`
-- [x] Added 7 individual parameters:
-  - `address: Optional[str] = None`
-  - `city: Optional[str] = None`
-  - `state: Optional[str] = None`
-  - `zipCode: Optional[str] = None`
-  - `limit: int = 10`
-  - `offset: int = 0`
-  - `force_refresh: bool = False`
-- [x] Removed `request.model_dump()` call
-- [x] Manually built params dict from individual parameters
-- [x] Updated all request field references to individual parameters
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 7. get_market_statistics
-- [x] Removed `request: MarketStatsRequest`
-- [x] Added 4 individual parameters:
-  - `city: Optional[str] = None`
-  - `state: Optional[str] = None`
-  - `zipCode: Optional[str] = None`
-  - `force_refresh: bool = False`
-- [x] Removed `request.model_dump()` call
-- [x] Manually built params dict from individual parameters
-- [x] Updated all request field references to individual parameters
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 8. expire_cache
-- [x] Removed `request: ExpireCacheRequest`
-- [x] Added 3 individual parameters:
-  - `cache_key: Optional[str] = None`
-  - `endpoint: Optional[str] = None`
-  - `all: bool = False`
-- [x] Updated all `request.all` to `all`
-- [x] Updated all `request.cache_key` to `cache_key`
-- [x] Updated all `request.endpoint` to `endpoint`
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
-### 9. set_api_limits
-- [x] Removed `request: SetLimitsRequest`
-- [x] Added 3 individual parameters:
-  - `daily_limit: Optional[int] = None`
-  - `monthly_limit: Optional[int] = None`
-  - `requests_per_minute: Optional[int] = None`
-- [x] Updated all `request.daily_limit` to `daily_limit`
-- [x] Updated all `request.monthly_limit` to `monthly_limit`
-- [x] Updated all `request.requests_per_minute` to `requests_per_minute`
-- [x] Added comprehensive docstring
-- [x] Verified function logic unchanged
-
----
-
-## Quality Assurance
-
-### Code Verification
-- [x] Python syntax check passed
-- [x] No remaining Pydantic request models in @app.tool() signatures
-- [x] All function bodies properly updated for individual parameters
-- [x] All docstrings include Args sections
-- [x] Default values match original model definitions
-
-### Type Consistency
-- [x] Required vs optional parameters correctly specified
-- [x] Default values match Pydantic model Field defaults
-- [x] Return types unchanged
-- [x] No breaking changes to function behavior
-
-### Documentation
-- [x] Refactoring summary created: `/home/rpm/claude/mcrentcast/REFACTORING_SUMMARY.md`
-- [x] Comprehensive before/after comparisons documented
-- [x] Benefits section explains the refactoring rationale
-- [x] All changes are traceable and reversible
-
----
-
-## Summary Statistics
-
-| Metric | Value |
-|--------|-------|
-| Total Tools Refactored | 9 |
-| Pydantic Models Removed from Signatures | 9 |
-| Individual Parameters Added | 35 |
-| Functions with Updated Logic | 6 (that used model_dump()) |
-| Docstrings Added/Enhanced | 9 |
-| Files Modified | 1 |
-| Lines Changed | 350+ |
-| Syntax Errors | 0 |
-| Breaking Changes | 0 |
-
----
-
-## Next Steps (Optional)
-
-### Consider For Future Work
-1. **Remove Unused Pydantic Models** - The following request model classes can be removed from lines 58-123 if no longer needed:
-   - SetApiKeyRequest
-   - PropertyByIdRequest
-   - ValueEstimateRequest
-   - RentEstimateRequest
-   - ListingSearchRequest
-   - ListingByIdRequest (never used)
-   - MarketStatsRequest
-   - ExpireCacheRequest
-   - SetLimitsRequest
-
-2. **Update Documentation** - Update any external API documentation or client libraries that reference these request models
-
-3. **Version Release** - Tag this as a new version (using date-based versioning: YYYY-MM-DD) to reflect the API changes
-
----
-
-## Status: COMPLETE
-
-All 9 MCP tools have been successfully refactored to use individual parameters instead of Pydantic model classes. The refactoring improves FastMCP protocol compatibility, code clarity, and maintainability.
-
-Date Completed: 2025-11-14
-Refactored by: Refactoring Expert Agent

src/mcrentcast/server.py

@@ -175,22 +175,18 @@ async def request_confirmation(endpoint: str, parameters: Dict[str, Any],
 # MCP Tool Definitions
 
 @app.tool()
-async def set_api_key(api_key: str) -> Dict[str, Any]:
+async def set_api_key(request: SetApiKeyRequest) -> Dict[str, Any]:
-    """Set or update the Rentcast API key for this session.
+    """Set or update the Rentcast API key for this session."""
-
+    settings.rentcast_api_key = request.api_key
-    Args:
-        api_key: Rentcast API key
-    """
-    settings.rentcast_api_key = api_key
     
     # Reinitialize client with new key
     global rentcast_client
     if rentcast_client:
         await rentcast_client.close()
-    rentcast_client = RentcastClient(api_key=api_key)
+    rentcast_client = RentcastClient(api_key=request.api_key)
     
     # Save to configuration
-    await db_manager.set_config("rentcast_api_key", api_key)
+    await db_manager.set_config("rentcast_api_key", request.api_key)
     
     logger.info("API key updated")
     return {
@@ -200,26 +196,8 @@ async def set_api_key(api_key: str) -> Dict[str, Any]:
 
 
 @app.tool()
-async def search_properties(
+async def search_properties(request: PropertySearchRequest) -> Dict[str, Any]:
-    address: Optional[str] = None,
+    """Search for property records by location."""
-    city: Optional[str] = None,
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    limit: int = 10,
-    offset: int = 0,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Search for property records by location.
-
-    Args:
-        address: Property address
-        city: City name
-        state: State code (e.g., CA, TX)
-        zipCode: ZIP code
-        limit: Max results (up to 500)
-        offset: Results offset for pagination
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured",
@@ -229,26 +207,16 @@ async def search_properties(
     client = get_rentcast_client()
     
     try:
-        # Build params dict
-        params = {
-            "address": address,
-            "city": city,
-            "state": state,
-            "zipCode": zipCode,
-            "limit": limit,
-            "offset": offset
-        }
-
         # Check if we need confirmation for non-cached request
-        cache_key = client._create_cache_key("property-records", params)
+        cache_key = client._create_cache_key("property-records", request.model_dump(exclude={"force_refresh"}))
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             # Request confirmation for new API call
             cost_estimate = client._estimate_cost("property-records")
             confirmed = await request_confirmation(
                 "property-records",
-                params,
+                request.model_dump(exclude={"force_refresh"}),
                 cost_estimate
             )
             
@@ -260,13 +228,13 @@ async def search_properties(
                 }
                 
         properties, is_cached, cache_age = await client.get_property_records(
-            address=address,
+            address=request.address,
-            city=city,
+            city=request.city,
-            state=state,
+            state=request.state,
-            zipCode=zipCode,
+            zipCode=request.zipCode,
-            limit=limit,
+            limit=request.limit,
-            offset=offset,
+            offset=request.offset,
-            force_refresh=force_refresh
+            force_refresh=request.force_refresh
         )
         
         return {
@@ -298,13 +266,8 @@ async def search_properties(
 
 
 @app.tool()
-async def get_property(property_id: str, force_refresh: bool = False) -> Dict[str, Any]:
+async def get_property(request: PropertyByIdRequest) -> Dict[str, Any]:
-    """Get detailed information for a specific property by ID.
+    """Get detailed information for a specific property by ID."""
-
-    Args:
-        property_id: Property ID from Rentcast
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured",
@@ -315,13 +278,13 @@ async def get_property(property_id: str, force_refresh: bool = False) -> Dict[st
     
     try:
         # Check cache and request confirmation if needed
-        cache_key = client._create_cache_key(f"property-record/{property_id}", {})
+        cache_key = client._create_cache_key(f"property-record/{request.property_id}", {})
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             cost_estimate = client._estimate_cost("property-record")
             confirmed = await request_confirmation(
-                f"property-record/{property_id}",
+                f"property-record/{request.property_id}",
                 {},
                 cost_estimate
             )
@@ -334,8 +297,8 @@ async def get_property(property_id: str, force_refresh: bool = False) -> Dict[st
                 }
                 
         property_record, is_cached, cache_age = await client.get_property_record(
-            property_id,
+            request.property_id,
-            force_refresh
+            request.force_refresh
         )
         
         if property_record:
@@ -361,13 +324,8 @@ async def get_property(property_id: str, force_refresh: bool = False) -> Dict[st
 
 
 @app.tool()
-async def get_value_estimate(address: str, force_refresh: bool = False) -> Dict[str, Any]:
+async def get_value_estimate(request: ValueEstimateRequest) -> Dict[str, Any]:
-    """Get property value estimate for an address.
+    """Get property value estimate for an address."""
-
-    Args:
-        address: Property address
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured",
@@ -378,14 +336,14 @@ async def get_value_estimate(address: str, force_refresh: bool = False) -> Dict[
     
     try:
         # Check cache and request confirmation if needed
-        cache_key = client._create_cache_key("value-estimate", {"address": address})
+        cache_key = client._create_cache_key("value-estimate", {"address": request.address})
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             cost_estimate = client._estimate_cost("value-estimate")
             confirmed = await request_confirmation(
                 "value-estimate",
-                {"address": address},
+                {"address": request.address},
                 cost_estimate
             )
             
@@ -397,8 +355,8 @@ async def get_value_estimate(address: str, force_refresh: bool = False) -> Dict[
                 }
                 
         estimate, is_cached, cache_age = await client.get_value_estimate(
-            address,
+            request.address,
-            force_refresh
+            request.force_refresh
         )
         
         if estimate:
@@ -424,24 +382,8 @@ async def get_value_estimate(address: str, force_refresh: bool = False) -> Dict[
 
 
 @app.tool()
-async def get_rent_estimate(
+async def get_rent_estimate(request: RentEstimateRequest) -> Dict[str, Any]:
-    address: str,
+    """Get rent estimate for a property."""
-    propertyType: Optional[str] = None,
-    bedrooms: Optional[int] = None,
-    bathrooms: Optional[float] = None,
-    squareFootage: Optional[int] = None,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Get rent estimate for a property.
-
-    Args:
-        address: Property address
-        propertyType: Property type (Single Family, Condo, etc.)
-        bedrooms: Number of bedrooms
-        bathrooms: Number of bathrooms
-        squareFootage: Square footage
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured", 
@@ -451,15 +393,9 @@ async def get_rent_estimate(
     client = get_rentcast_client()
     
     try:
-        params = {
+        params = request.model_dump(exclude={"force_refresh"})
-            "address": address,
-            "propertyType": propertyType,
-            "bedrooms": bedrooms,
-            "bathrooms": bathrooms,
-            "squareFootage": squareFootage
-        }
         cache_key = client._create_cache_key("rent-estimate-long-term", params)
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             cost_estimate = client._estimate_cost("rent-estimate-long-term")
@@ -477,12 +413,12 @@ async def get_rent_estimate(
                 }
                 
         estimate, is_cached, cache_age = await client.get_rent_estimate(
-            address=address,
+            address=request.address,
-            propertyType=propertyType,
+            propertyType=request.propertyType,
-            bedrooms=bedrooms,
+            bedrooms=request.bedrooms,
-            bathrooms=bathrooms,
+            bathrooms=request.bathrooms,
-            squareFootage=squareFootage,
+            squareFootage=request.squareFootage,
-            force_refresh=force_refresh
+            force_refresh=request.force_refresh
         )
         
         if estimate:
@@ -508,26 +444,8 @@ async def get_rent_estimate(
 
 
 @app.tool()
-async def search_sale_listings(
+async def search_sale_listings(request: ListingSearchRequest) -> Dict[str, Any]:
-    address: Optional[str] = None,
+    """Search for properties for sale."""
-    city: Optional[str] = None,
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    limit: int = 10,
-    offset: int = 0,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Search for properties for sale.
-
-    Args:
-        address: Property address
-        city: City name
-        state: State code
-        zipCode: ZIP code
-        limit: Max results (up to 500)
-        offset: Results offset for pagination
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured",
@@ -537,16 +455,9 @@ async def search_sale_listings(
     client = get_rentcast_client()
     
     try:
-        params = {
+        params = request.model_dump(exclude={"force_refresh"})
-            "address": address,
-            "city": city,
-            "state": state,
-            "zipCode": zipCode,
-            "limit": limit,
-            "offset": offset
-        }
         cache_key = client._create_cache_key("sale-listings", params)
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             cost_estimate = client._estimate_cost("sale-listings")
@@ -564,13 +475,13 @@ async def search_sale_listings(
                 }
                 
         listings, is_cached, cache_age = await client.get_sale_listings(
-            address=address,
+            address=request.address,
-            city=city,
+            city=request.city,
-            state=state,
+            state=request.state,
-            zipCode=zipCode,
+            zipCode=request.zipCode,
-            limit=limit,
+            limit=request.limit,
-            offset=offset,
+            offset=request.offset,
-            force_refresh=force_refresh
+            force_refresh=request.force_refresh
         )
         
         return {
@@ -591,26 +502,8 @@ async def search_sale_listings(
 
 
 @app.tool()
-async def search_rental_listings(
+async def search_rental_listings(request: ListingSearchRequest) -> Dict[str, Any]:
-    address: Optional[str] = None,
+    """Search for rental properties."""
-    city: Optional[str] = None,
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    limit: int = 10,
-    offset: int = 0,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Search for rental properties.
-
-    Args:
-        address: Property address
-        city: City name
-        state: State code
-        zipCode: ZIP code
-        limit: Max results (up to 500)
-        offset: Results offset for pagination
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured",
@@ -620,16 +513,9 @@ async def search_rental_listings(
     client = get_rentcast_client()
     
     try:
-        params = {
+        params = request.model_dump(exclude={"force_refresh"})
-            "address": address,
-            "city": city,
-            "state": state,
-            "zipCode": zipCode,
-            "limit": limit,
-            "offset": offset
-        }
         cache_key = client._create_cache_key("rental-listings-long-term", params)
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             cost_estimate = client._estimate_cost("rental-listings-long-term")
@@ -647,13 +533,13 @@ async def search_rental_listings(
                 }
                 
         listings, is_cached, cache_age = await client.get_rental_listings(
-            address=address,
+            address=request.address,
-            city=city,
+            city=request.city,
-            state=state,
+            state=request.state,
-            zipCode=zipCode,
+            zipCode=request.zipCode,
-            limit=limit,
+            limit=request.limit,
-            offset=offset,
+            offset=request.offset,
-            force_refresh=force_refresh
+            force_refresh=request.force_refresh
         )
         
         return {
@@ -674,20 +560,8 @@ async def search_rental_listings(
 
 
 @app.tool()
-async def get_market_statistics(
+async def get_market_statistics(request: MarketStatsRequest) -> Dict[str, Any]:
-    city: Optional[str] = None,
+    """Get market statistics for a location."""
-    state: Optional[str] = None,
-    zipCode: Optional[str] = None,
-    force_refresh: bool = False
-) -> Dict[str, Any]:
-    """Get market statistics for a location.
-
-    Args:
-        city: City name
-        state: State code
-        zipCode: ZIP code
-        force_refresh: Force cache refresh
-    """
     if not await check_api_key():
         return {
             "error": "API key not configured",
@@ -697,13 +571,9 @@ async def get_market_statistics(
     client = get_rentcast_client()
     
     try:
-        params = {
+        params = request.model_dump(exclude={"force_refresh"})
-            "city": city,
-            "state": state,
-            "zipCode": zipCode
-        }
         cache_key = client._create_cache_key("market-statistics", params)
-        cached_entry = await db_manager.get_cache_entry(cache_key) if not force_refresh else None
+        cached_entry = await db_manager.get_cache_entry(cache_key) if not request.force_refresh else None
         
         if not cached_entry:
             cost_estimate = client._estimate_cost("market-statistics")
@@ -721,10 +591,10 @@ async def get_market_statistics(
                 }
                 
         stats, is_cached, cache_age = await client.get_market_statistics(
-            city=city,
+            city=request.city,
-            state=state,
+            state=request.state,
-            zipCode=zipCode,
+            zipCode=request.zipCode,
-            force_refresh=force_refresh
+            force_refresh=request.force_refresh
         )
         
         if stats:
@@ -750,29 +620,19 @@ async def get_market_statistics(
 
 
 @app.tool()
-async def expire_cache(
+async def expire_cache(request: ExpireCacheRequest) -> Dict[str, Any]:
-    cache_key: Optional[str] = None,
+    """Expire cache entries to force fresh API calls."""
-    endpoint: Optional[str] = None,
-    all: bool = False
-) -> Dict[str, Any]:
-    """Expire cache entries to force fresh API calls.
-
-    Args:
-        cache_key: Specific cache key to expire
-        endpoint: Expire all cache for endpoint
-        all: Expire all cache entries
-    """
     try:
-        if all:
+        if request.all:
             # Clean all expired entries
             count = await db_manager.clean_expired_cache()
             return {
                 "success": True,
                 "message": f"Expired {count} cache entries"
             }
-        elif cache_key:
+        elif request.cache_key:
             # Expire specific cache key
-            expired = await db_manager.expire_cache_entry(cache_key)
+            expired = await db_manager.expire_cache_entry(request.cache_key)
             return {
                 "success": expired,
                 "message": "Cache entry expired" if expired else "Cache entry not found"
@@ -828,30 +688,20 @@ async def get_usage_stats(days: int = Field(30, description="Number of days to i
 
 
 @app.tool()
-async def set_api_limits(
+async def set_api_limits(request: SetLimitsRequest) -> Dict[str, Any]:
-    daily_limit: Optional[int] = None,
+    """Update API rate limits and usage quotas."""
-    monthly_limit: Optional[int] = None,
-    requests_per_minute: Optional[int] = None
-) -> Dict[str, Any]:
-    """Update API rate limits and usage quotas.
-
-    Args:
-        daily_limit: Daily API request limit
-        monthly_limit: Monthly API request limit
-        requests_per_minute: Requests per minute limit
-    """
     try:
-        if daily_limit is not None:
+        if request.daily_limit is not None:
-            await db_manager.set_config("daily_api_limit", daily_limit)
+            await db_manager.set_config("daily_api_limit", request.daily_limit)
-            settings.daily_api_limit = daily_limit
+            settings.daily_api_limit = request.daily_limit
             
-        if monthly_limit is not None:
+        if request.monthly_limit is not None:
-            await db_manager.set_config("monthly_api_limit", monthly_limit)
+            await db_manager.set_config("monthly_api_limit", request.monthly_limit)
-            settings.monthly_api_limit = monthly_limit
+            settings.monthly_api_limit = request.monthly_limit
             
-        if requests_per_minute is not None:
+        if request.requests_per_minute is not None:
-            await db_manager.set_config("requests_per_minute", requests_per_minute)
+            await db_manager.set_config("requests_per_minute", request.requests_per_minute)
-            settings.requests_per_minute = requests_per_minute
+            settings.requests_per_minute = request.requests_per_minute
             
         return {
             "success": True,