# Design Decision: Tool Parsing Simplification

**Date:** 2024-02-24
**Scope:** src/api/routes.py parse_tool_calls function
**Lines Changed:** ~210 lines removed, ~30 lines added

## Problem

The tool parsing code had accumulated 4 different parsing formats over 25+ commits:
1. JSON `tool_calls` format with nested objects
2. TOOL:/ARGUMENTS: format (simple text)
3. Function pattern format `func_name(args)`
4. Multiple JSON handling variants

This caused:
- Circular development (adding/removing formats repeatedly)
- No single source of truth
- Complex, unmaintainable code
- No confidence that changes wouldn't break existing cases

## Options Considered

### Option 1: Keep All Formats
- **Pros:** Backward compatible
- **Cons:** 210 lines of unmaintainable code, continues circular development pattern
- **Verdict:** REJECTED - Perpetuates the problem

### Option 2: Standardize on TOOL:/ARGUMENTS: Only
- **Pros:** 
  - Simple regex pattern (~30 lines)
  - Matches current tool instructions
  - Easy to test
  - Clear single format for models
- **Cons:** 
  - Breaking change if any code relies on old formats
  - Need to update any existing examples/docs
- **Verdict:** ACCEPTED - Aligns with Rule 5 (Parse Once, Parse Well)

### Option 3: Create Parser per Format with Feature Flags
- **Pros:** Flexible, can toggle formats
- **Cons:** 
  - Violates Rule 5 and "No Feature Flags in Core Logic"
  - Still maintains multiple code paths
- **Verdict:** REJECTED - Doesn't solve the root problem

## Decision

Standardize on the TOOL:/ARGUMENTS: format only. Remove all other parsing code.

**Rationale:**
- Per DEVELOPMENT_PATTERNS.md recommendation #3: "One Format Only"
- Token cost is minimal (no complex regex)
- Test coverage provides confidence
- Aligns with existing tool instructions

## Impact

### Token Count
- **Parser code:** 210 lines → 30 lines (-180 lines)
- **No change** to tool instructions (separate optimization)

### Breaking Changes
- **Yes** - Removes support for:
  - JSON `tool_calls` format in model responses
  - Function pattern format `read_file(path="test.txt")`
  
**Migration:** Models must use:
```
TOOL: read
ARGUMENTS: {"filePath": "test.txt"}
```

### Testing
- Unit tests added: 9 test cases
- Coverage: All parsing scenarios
- All tests pass

## Implementation

```python
# New implementation (30 lines)
def parse_tool_calls(text: str) -> tuple:
    """Parse tool calls using standardized format."""
    import json
    import re
    
    tool_pattern = r'TOOL:\s*(\w+)\s*\nARGUMENTS:\s*(\{[^}]*\})'
    tool_matches = list(re.finditer(tool_pattern, text, re.IGNORECASE))
    
    if not tool_matches:
        return text, None
    
    tool_calls = []
    for i, tool_match in enumerate(tool_matches):
        tool_name = tool_match.group(1)
        args_str = tool_match.group(2)
        try:
            args_dict = json.loads(args_str)
            tool_calls.append({
                "id": f"call_{i+1}",
                "type": "function", 
                "function": {
                    "name": tool_name,
                    "arguments": json.dumps(args_dict)
                }
            })
        except json.JSONDecodeError:
            continue
    
    if not tool_calls:
        return text, None
    
    first_start = tool_matches[0].start()
    content = text[:first_start].strip()
    
    return content, tool_calls
```

## Verification

Run tests:
```bash
python tests/test_tool_parsing.py
```

Expected: 9 passed, 0 failed

## Follow-up

- [x] Update DEVELOPMENT_PATTERNS.md to mark as completed
- [x] Add unit tests
- [ ] Consider integration test for full tool execution flow