Beginner-Friendly Topic

Take your time - it's perfectly normal to re-read this topic 2-3 times. Try the interactive code editor below to run code yourself. Use the Q&A section to check your understanding before moving on.You've got this!

Tool Outputs

Tool outputs are the values the tool returns to the agent as observations. The output format should be consistent and clear so the agent can parse and use the result reliably.

6 min•By Priygop Team•Updated 2026

Output Design Principles

Always return a structured result, not free-form text — dictionaries and lists are easier for agents to parse
Include a status field (success/error) so the agent knows if the tool ran correctly
Include the relevant data in a predictable field name (e.g., 'result', 'data', 'records')
Include metadata where useful: count of records, timestamp, source URL
For errors, include an 'error' field with a clear, human-readable description
Keep outputs concise — very large outputs use tokens and slow down the agent

Output Format Examples

# Good output format examples

# Search tool output
search_result = {
    "status": "success",
    "query": "Python web scraping libraries",
    "count": 3,
    "results": [
        {"title": "BeautifulSoup", "url": "https://example.com/1", "snippet": "Simple HTML parsing..."},
        {"title": "Scrapy", "url": "https://example.com/2", "snippet": "Full-featured scraping framework..."},
        {"title": "Playwright", "url": "https://example.com/3", "snippet": "Browser automation..."},
    ]
}

# Database query output
db_result = {
    "status": "success",
    "table": "orders",
    "count": 2,
    "records": [
        {"id": 101, "product": "Laptop", "status": "shipped"},
        {"id": 102, "product": "Mouse", "status": "pending"},
    ]
}

# Error output
error_result = {
    "status": "error",
    "error": "Database connection timeout after 30 seconds",
    "retry_after": 5  # seconds
}

print("Status:", search_result["status"])
print("Results count:", search_result["count"])

Key Takeaways

Tool outputs are the values the tool returns to the agent as observations.
Always return a structured result, not free-form text — dictionaries and lists are easier for agents to parse
Include a status field (success/error) so the agent knows if the tool ran correctly
Include the relevant data in a predictable field name (e.g., 'result', 'data', 'records')

Topics in This Module

Output Design Principles

Always return a structured result, not free-form text — dictionaries and lists are easier for agents to parse

Include a status field (success/error) so the agent knows if the tool ran correctly

Include the relevant data in a predictable field name (e.g., 'result', 'data', 'records')

Include metadata where useful: count of records, timestamp, source URL

For errors, include an 'error' field with a clear, human-readable description

Keep outputs concise — very large outputs use tokens and slow down the agent

Output Format Examples

# Good output format examples

# Search tool output
search_result = {
    "status": "success",
    "query": "Python web scraping libraries",
    "count": 3,
    "results": [
        {"title": "BeautifulSoup", "url": "https://example.com/1", "snippet": "Simple HTML parsing..."},
        {"title": "Scrapy", "url": "https://example.com/2", "snippet": "Full-featured scraping framework..."},
        {"title": "Playwright", "url": "https://example.com/3", "snippet": "Browser automation..."},
    ]
}

# Database query output
db_result = {
    "status": "success",
    "table": "orders",
    "count": 2,
    "records": [
        {"id": 101, "product": "Laptop", "status": "shipped"},
        {"id": 102, "product": "Mouse", "status": "pending"},
    ]
}

# Error output
error_result = {
    "status": "error",
    "error": "Database connection timeout after 30 seconds",
    "retry_after": 5  # seconds
}

print("Status:", search_result["status"])
print("Results count:", search_result["count"])

Topics in This Module