tool-interface-analysis

What this skill does

# Tool Interface Analysis

Analyzes how agent frameworks model, register, and execute tools. This skill examines the **tool abstraction layer**, **schema generation**, **built-in inventory**, and **error feedback mechanisms**.

## Distinction from harness-model-protocol

| tool-interface-analysis | harness-model-protocol |
|------------------------|------------------------|
| How a "tool" is represented (types, base classes) | How tool calls are encoded on the wire |
| Schema generation (Pydantic -> JSON Schema) | Schema transmission to LLM API |
| Built-in tool inventory | Provider-specific tool formats |
| Registration and discovery patterns | Message format translation |
| Error feedback to LLM for retry | Response parsing and streaming |
| Tool execution orchestration | Partial tool call handling |

## Process

1. **Map tool modeling** - Identify how tools are represented (types, protocols, base classes)
2. **Analyze schema generation** - How tool definitions become JSON Schema
3. **Catalog built-in inventory** - What tools ship with the framework
4. **Trace registration flow** - How tools are discovered and made available
5. **Document execution patterns** - Invocation, validation, error handling
6. **Evaluate retry mechanisms** - Self-correction and feedback loops

## Tool Modeling Patterns

### Abstract Base Class Pattern

```python
from abc import ABC, abstractmethod
from typing import Any

class BaseTool(ABC):
    """Framework's tool abstraction."""
    name: str
    description: str

    @abstractmethod
    def execute(self, **kwargs) -> Any:
        """Execute the tool with validated arguments."""
        ...

    @property
    @abstractmethod
    def parameters_schema(self) -> dict:
        """Return JSON Schema for parameters."""
        ...
```

**Characteristics**: Explicit contract, inheritance-based, type-safe
**Used by**: LangChain, CrewAI, AutoGen

### Protocol/Interface Pattern

```python
from typing import Protocol, runtime_checkable

@runtime_checkable
class Tool(Protocol):
    """Structural typing for tools."""
    name: str
    description: str

    def __call__(self, **kwargs) -> Any: ...
    def get_schema(self) -> dict: ...
```

**Characteristics**: Duck typing, flexible, composition-friendly
**Used by**: Pydantic-AI, OpenAI Agents SDK

### Decorated Function Pattern

```python
from functools import wraps

def tool(name: str = None, description: str = None):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            return func(*args, **kwargs)
        wrapper._tool_name = name or func.__name__
        wrapper._tool_description = description or func.__doc__
        wrapper._is_tool = True
        return wrapper
    return decorator

@tool(description="Search the web for information")
def search(query: str, max_results: int = 10) -> list[str]:
    ...
```

**Characteristics**: Lightweight, DRY, preserves function identity
**Used by**: Google ADK, Swarm, Function calling patterns

### Pydantic Model Pattern

```python
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    """Input schema for search tool."""
    query: str = Field(description="The search query")
    max_results: int = Field(default=10, ge=1, le=100)

class SearchTool(BaseTool):
    name = "search"
    description = "Search the web"
    args_schema = SearchInput

    def execute(self, **kwargs) -> list[str]:
        validated = SearchInput(**kwargs)
        return perform_search(validated.query, validated.max_results)
```

**Characteristics**: Rich validation, auto-schema, clear separation
**Used by**: LangChain, CrewAI

## Schema Generation Methods

### Introspection-Based (Automatic)

```python
import inspect
from typing import get_type_hints

def generate_schema_from_function(func) -> dict:
    hints = get_type_hints(func)
    sig = inspect.signature(func)
    doc = inspect.getdoc(func) or ""

    schema = {
        "type": "function",
        "function": {
            "name": func.__name__,
            "description": doc.split("\n")[0],
            "parameters": {
                "type": "object",
                "properties": {},
                "required": []
            }
        }
    }

    for name, param in sig.parameters.items():
        if name in ("self", "cls"):
            continue

        prop = {"type": python_type_to_json(hints.get(name, str))}

        # Extract description from docstring if available
        if f":param {name}:" in doc:
            prop["description"] = extract_param_doc(doc, name)

        if param.default is inspect.Parameter.empty:
            schema["function"]["parameters"]["required"].append(name)
        else:
            prop["default"] = param.default

        schema["function"]["parameters"]["properties"][name] = prop

    return schema
```

**Pros**: DRY, always in sync with code, minimal boilerplate
**Cons**: Limited expressiveness, relies on annotations, docstring parsing fragile

### Pydantic-Based (Semi-Automatic)

```python
from pydantic import BaseModel, Field
from pydantic.json_schema import GenerateJsonSchema

class SearchInput(BaseModel):
    """Search the web for information."""
    query: str = Field(description="The search query")
    max_results: int = Field(default=10, ge=1, le=100, description="Max results to return")

def generate_schema_from_pydantic(model: type[BaseModel]) -> dict:
    return {
        "type": "function",
        "function": {
            "name": model.__name__.replace("Input", "").lower(),
            "description": model.__doc__ or "",
            "parameters": model.model_json_schema()
        }
    }
```

**Pros**: Rich validation, excellent descriptions, composable
**Cons**: Class per tool, more boilerplate, Pydantic dependency

### Decorator-Based (Explicit)

```python
@tool(
    name="search",
    description="Search the web for information",
    parameters={
        "query": {"type": "string", "description": "Search query"},
        "max_results": {"type": "integer", "default": 10}
    }
)
def search(query: str, max_results: int = 10) -> list[str]:
    ...
```

**Pros**: Explicit, flexible, no dependencies
**Cons**: Can drift from implementation, manual maintenance

### Manual Definition

```python
TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "search",
            "description": "Search the web for information",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query"
                    }
                },
                "required": ["query"]
            }
        }
    }
]
```

**Pros**: Full control, no magic, portable
**Cons**: Maintenance burden, drift risk, duplication

### Schema Generation Comparison

| Method | Sync with Code | Expressiveness | Boilerplate | Validation |
|--------|---------------|----------------|-------------|------------|
| Introspection | Automatic | Low | None | None |
| Pydantic | Automatic | High | Medium | Built-in |
| Decorator | Manual | Medium | Low | Optional |
| Manual | Manual | Full | High | None |

## Registration Patterns

### Declarative List

```python
agent = Agent(
    tools=[search_tool, calculator_tool, weather_tool]
)
```

**Characteristics**: Explicit, static, easy to understand, testable

### Registry Pattern

```python
TOOL_REGISTRY = {}

def register_tool(name: str = None):
    def decorator(func):
        tool_name = name or func.__name__
        TOOL_REGISTRY[tool_name] = func
        return func
    return decorator

@register_tool("search")
def search(query: str) -> list[str]: ...

# Agent uses registry
agent = Agent(tools=list(TOOL_REGISTRY.values()))
```

**Characteristics**: Dynamic, plugin-friendly, implicit coupling

### Discovery-Based (Auto-Import)

```python
import importlib
import pkgutil

def discover_tools(package):
    tools = []
    for