Skip to main content
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.tools 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)
​
cache_results
bool
default:"false"
Enable result caching for this tool.
​
cache_ttl
int
default:"3600"
Cache time-to-live in seconds. Results older than this are re-fetched.
​
cache_dir
str
Directory to store cache files. Defaults to a system temp directory.

​
How It Works

  1. When a tool is called, the arguments are serialized to a cache key
  2. If a cached result exists and is within the TTL, it is returned immediately
  3. 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.tools 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)