09. Tool Output Handling

Tool output formatting determines how execution results influence subsequent model behavior. Well-structured outputs help models interpret results and decide next actions.

Design outputs with consistent structure:

def format_tool_output(tool_name: str, result: Any, success: bool = True) -> dict:
    return {
        "status": "success" if success else "error",
        "tool": tool_name,
        "data": result,
        "timestamp": datetime.now().isoformat()
    }

Scalar values embedded in this structure:

# Tool returns: {"city": "Boston", "temp": 72, "conditions": "sunny"}
# Formatted output:
{
    "status": "success",
    "tool": "get_weather",
    "data": {
        "city": "Boston",
        "temp": 72,
        "conditions": "sunny"
    },
    "timestamp": "2026-05-29T14:30:00"
}

Truncation prevents large outputs from exceeding context limits:

def truncate_output(data: Any, max_chars: int = 2000) -> str:
    serialized = json.dumps(data)
    
    if len(serialized) <= max_chars:
        return serialized
    
    return serialized[:max_chars] + f"\n... [truncated {len(serialized) - max_chars} characters]"

Table data requires special formatting:

def format_table_output(data: list[dict]) -> str:
    if not data:
        return "No results found"
    
    keys = list(data[0].keys())
    header = " | ".join(keys)
    separator = "|".join(["---" for _ in keys])
    
    rows = []
    for item in data[:10]:  # Limit rows
        row = " | ".join(str(item.get(k, "")) for k in keys)
        rows.append(row)
    
    return f"{header}\n{separator}\n" + "\n".join(rows)

Error output formatting helps models retry or adapt:

def format_error_output(tool_name: str, error: Exception, context: dict = None) -> dict:
    return {
        "status": "error",
        "tool": tool_name,
        "error_type": type(error).__name__,
        "message": str(error),
        "recoverable": isinstance(error, (TimeoutError, ConnectionError, RateLimitError)),
        "suggestion": get_error_suggestion(error),
        "context": context
    }

def get_error_suggestion(error: Exception) -> str:
    suggestions = {
        "ConnectionError": "Check network connectivity and service availability",
        "TimeoutError": "The operation took too long—consider retrying with a larger timeout",
        "ValueError": "Invalid input parameters—verify argument format",
        "PermissionError": "Insufficient permissions—check access rights"
    }
    return suggestions.get(type(error).__name__, "Unknown error—check service configuration")

Summarization for large outputs:

def summarize_large_output(data: Any, max_length: int = 500) -> str:
    if isinstance(data, list):
        summary = f"Found {len(data)} results. "
        if data:
            sample = data[:3]
            summary += f"First items: {json.dumps(sample)}"
        return summary[:max_length]
    elif isinstance(data, dict):
        keys = list(data.keys())[:5]
        summary = f"Object with {len(data)} keys: {', '.join(keys)}"
        return summary
    else:
        return str(data)[:max_length]

Chain-of-thought prompting helps models process complex outputs:

SYSTEM_PROMPT = """You have access to tools. When you receive tool results:
1. Read the status field to check if the tool succeeded
2. Extract the relevant data from the "data" field
3. Determine if additional tool calls are needed
4. If errors occurred, decide whether to retry with modified arguments or try a different approach

Format your response to be helpful and concise."""