Tool Caching

Tool caching stores results for previously seen arguments, so repeated calls with the same input return instantly without re-executing the function.

Enabling Caching

Set cache_results=True on the @tool decorator:

from definable.tool.decorator import tool

@tool(cache_results=True)
def search_database(query: str) -> str:
    """Search the database (expensive operation)."""
    # This only runs once per unique query
    return expensive_db_query(query)

Cache TTL

Control how long cached results remain valid:

@tool(cache_results=True, cache_ttl=1800)  # 30 minutes
def get_stock_price(symbol: str) -> str:
    """Get the current stock price."""
    return fetch_price(symbol)

bool

default:"false"

Enable result caching for this tool.

int

default:"3600"

Cache time-to-live in seconds. Results older than this are re-fetched.

str

Directory to store cache files. Defaults to a system temp directory.

How It Works

When a tool is called, the arguments are serialized to a cache key
If a cached result exists and is within the TTL, it is returned immediately
If no cache hit, the function executes and the result is stored

Cache keys are based on the function name and a hash of the serialized arguments, so different inputs always produce different cache entries.

When to Use Caching

Caching works best for:

Expensive API calls — external search, database queries, web scraping
Deterministic functions — same input always produces the same output
Frequently repeated calls — agents that search for the same thing multiple times in a conversation

Do not cache tools with side effects (sending emails, writing to databases) or tools that return time-sensitive data where staleness matters.

Example: Caching an API Call

import httpx
from definable.tool.decorator import tool

@tool(cache_results=True, cache_ttl=300)  # 5-minute cache
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    resp = httpx.get(f"https://api.weather.com/current?city={city}")
    data = resp.json()
    return f"{data['temp']}°F, {data['condition']}"

The first call for each city hits the API. Subsequent calls within 5 minutes return the cached result.

Custom Cache Directory

@tool(cache_results=True, cache_dir="./cache/tools")
def expensive_analysis(text: str) -> str:
    """Run expensive text analysis."""
    return analyze(text)

Get Started

Basics

Capabilities

Advanced

Enabling Caching

Cache TTL

How It Works

When to Use Caching

Example: Caching an API Call

Custom Cache Directory

​Enabling Caching

​Cache TTL

​How It Works

​When to Use Caching

​Example: Caching an API Call

​Custom Cache Directory

Enabling Caching

Cache TTL

How It Works

When to Use Caching

Example: Caching an API Call

Custom Cache Directory