tool-builder

# How to Build a Tool

*Technical guide based on successful tool development patterns*

## Core Concepts

Effective tool building leverages two different types of pattern recognition:
- **Human perspective**: Real-world usage patterns, social dynamics, UX intuition
- **AI perspective**: System architecture, technical constraints, code consistency

Neither perspective alone produces optimal tools. The best solutions emerge from the intersection.

## Development Process

### Phase 1: Requirements Discovery

Initial descriptions often use metaphors or analogies. Extract concrete requirements:

```
Example: "Like 90s pagers"
Extracted requirements:
- High urgency messaging only
- Minimal UI complexity  
- Respects user attention
- No feature creep
```

Essential questions:
- "Can you walk me through a typical usage scenario?"
- "What problem does this solve that existing tools don't?"
- "What should this tool explicitly NOT do?"
- "What would indicate success for users?"

### Phase 2: Specification Analysis

Detailed specifications often contain both explicit features and implicit design philosophy. Minor details frequently encode critical constraints.

Example: If a spec mentions "no notification fatigue," this implies rate limiting, priority systems, or other attention-management features.

### Phase 3: Codebase Pattern Study

```python
# Required reading before implementation
tools/implementations/reminder_tool.py    # Complete tool example
tools/implementations/contacts_tool.py    # Tool with UUID linking
tools/implementations/punchclock_tool.py  # Tool with dependency injection
tools/repo.py                             # Base class and ToolRepository
utils/userdata_manager.py                 # Database API reference
```

Deviating from established patterns causes integration issues and maintenance debt.

### Phase 4: Incremental Implementation

Build order matters:
1. Data models (foundational structure)
2. Basic CRUD operations  
3. Core business logic
4. Complex features
5. Security/validation layers

```python
# Progress tracking
TodoWrite({
    "todos": [
        {"content": "Create data models", "activeForm": "Creating data models", "status": "pending"},
        {"content": "Implement basic operations", "activeForm": "Implementing basic operations", "status": "pending"},
        {"content": "Add validation", "activeForm": "Adding validation", "status": "pending"}
    ]
})

# Error handling pattern
def _add_item(self, title: str, **kwargs) -> Dict[str, Any]:
    if not title:
        self.logger.error("Title is required")
        raise ValueError("Title is required for this operation")

    try:
        # Implementation
        item_id = str(uuid.uuid4())
        timestamp = format_utc_iso(utc_now())

        self.db.insert('items', {
            'id': item_id,
            'title': title,
            'created_at': timestamp
        })

        return {"success": True, "item_id": item_id}

    except Exception as e:
        self.logger.error(f"Failed to add item: {e}")
        raise
```

### Phase 5: Collaborative Solution Design

Real workshopping between skilled practitioners - direct but not theatrical:

```
H: "Need a high-urgency notification tool. Think 90s pagers - when it goes off,
    it matters. No spam, no noise."

AI: "So restricted senders? Like an allowlist of who can page you?"

H: "Allowlists are a pain to manage upfront. What if we make people solve a
    captcha before they can send?"

AI: "That won't work - you'd need an external captcha service, and if someone has
    an actual emergency they shouldn't be solving puzzles."

H: "Fair point. What about a time delay? Message sits for 30 seconds before
    sending, gives them time to reconsider?"

AI: "Same problem - real emergencies need immediate delivery. And a delay doesn't
    actually filter importance, it just annoys people."

H: "Okay, back to allowlist but somehow less annoying?"

AI: "What if we flip it - first message from a new sender goes to a review queue.
    You see it, approve or block them once, then future messages are automatic."

H: "So it's still an allowlist, just built retroactively instead of upfront?"

AI: "Right. You're not maintaining a list ahead of time. Someone sends, you review
    that specific message, make a decision, done."

H: "I like that better. But what happens when someone gets a new phone? Their
    device changed, so..."

AI: "Yeah we'd need device fingerprinting. Store a hash of their browser/device,
    check it when they send. If the hash changes, route back to review queue."

H: "That's gonna annoy people though. People upgrade phones all the time."

AI: "True. We could show context when it happens - 'New device detected for Mom,
    last device was used 2 weeks ago' so you can decide if that timing makes sense."

H: "Okay yeah, that way it's not just silently blocking them. What about message
    length? I want them short."

AI: "How short are we talking?"

H: "I don't know, maybe 300 characters? That's long enough for 'stuck in traffic,
    start the meeting without me' but short enough to force brevity."

AI: "A hard 300 char limit is pretty restrictive. What if someone has a real
    reason to send more detail?"

H: "Then it's not urgent enough for this tool, use regular messaging."

AI: "Sure, but people will push back on that. What if we auto-summarize messages
    over 300 chars instead of blocking them?"

H: "Using the LLM?"

AI: "Yeah, run it through summarization, show the summary to you by default, but
    the full message is still there if you click to expand."

H: "Does that defeat the whole brevity thing though?"

AI: "Not really - you still see brevity on your end. The sender just doesn't get
    blocked from expressing themselves. We're translating verbose to concise
    instead of punishing verbose."

H: "Okay I can see that working. So schema-wise we need operations for sending,
    approving, and blocking. Device hash field. Message field and summary fi