Skip to main content

​
Basic Usage

Add functions directly as tools: 
def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"Weather in {location}: 22°C"

agent = Agent(
    name="weather_agent",
    model="openai/gpt-4o-mini",
    tools=[get_weather]  # Function automatically becomes a tool
)

​
Tool Configuration

Use the Tool type for custom descriptions and parameter control. The handler parameter is required and must be the function: 
from timbal import Tool

agent = Agent(
    name="weather_agent",
    model="openai/gpt-4o-mini",
    tools=[Tool(handler=get_weather)]
)

​
Custom Description

If the function name or docstring doesn’t clearly describe what the tool does, add a custom description. This is the description the LLM sees about the tool: 
Tool(
    handler=get_weather,
    description="Get current weather information for any location"
)

​
Parameter Visibility

When a tool has many parameters, reduce tokens and avoid overwhelming the LLM by showing only required parameters: 
Tool(
    handler=search,
    schema_params_mode="required"  # Only show required params (default: "all")
)
You can also include or exclude specific parameters to fine-tune what the LLM sees: 
# Include extra parameters even in "required" mode
Tool(
    handler=search_function,
    schema_params_mode="required",
    schema_include_params=["model"]  # Include this optional param
)

# Exclude sensitive or internal parameters
Tool(
    handler=api_function,
    schema_exclude_params=["api_key", "debug_mode"]  # Hide from LLM
)

​
Default Parameters

Set default values that are automatically applied when the tool is called. These values are used when not specified by the LLM: 
Tool(
    handler=database_query,
    default_params={
        "timeout": 30
    }
)
You can also use functions or environment variables as default parameters: 
def get_current_timestamp():
    return datetime.now().isoformat()

def process_data(data: str, timestamp: str | None = None, user_id: str = "default"):
    return f"Processed {data} at {timestamp} by {user_id}"

# Tool with dynamic default parameters
tool = Tool(
    name="data_processor",
    handler=process_data,
    default_params={
        "timestamp": get_current_timestamp,
        "user_id": "system_user"
    }
)

​
Built-in Tools

Timbal provides built-in tools for common use cases. These tools are ready to use and don’t require implementing handlers.

​
WebSearch

WebSearch enables agents to search the web.
WebSearch only works with OpenAI and Anthropic models. It’s a specification-only tool that defines the tool schema for the LLM but doesn’t contain executable logic. The actual web search execution is handled by the model provider. Other model providers are not supported.
from timbal import Agent
from timbal.tools import WebSearch

agent = Agent(
    name="research_agent",
    model="openai/gpt-4o-mini",
    tools=[
        WebSearch(
            allowed_domains=["wikipedia.org", "github.com"],  # Restrict to specific domains
            user_location={
                "type": "approximate",
                "country": "US",
                "city": "New York"
            }  # Localize results
        )
    ]
)
Available options:
  • allowed_domains: List of domains to restrict searches to
  • blocked_domains: List of domains to exclude (Anthropic only)
  • user_location: Dictionary with location info to localize search results. Must include type field. Common values are "approximate" or "exact", but valid values depend on the provider.

​
Multiple Instances of the Same Tool

If you need multiple instances of the same built-in tool with different configurations, they will have the same name by default, which causes conflicts. Set unique names and descriptions for each instance: 
general_search = WebSearch()
general_search.name = "general_search"
general_search.description = "Search the web for general information."

domain_search = WebSearch(allowed_domains=["example.com"])
domain_search.name = "domain_search"
domain_search.description = "Search only within example.com domain."

agent = Agent(
    name="research_agent",
    model="anthropic/claude-opus-4-latest",
    tools=[general_search, domain_search]
)

​
Agent as a Tool

You can use an Agent as a tool within another Agent, enabling hierarchical agent compositions where specialized agents handle specific tasks. Since Agent instances can be treated as Tool objects, they inherit the same parameter control configurations available to regular tools. 
from timbal import Agent

def calculate_cost(days: int, hotel_rate: float, flights: float = 0) -> float:
    """Calculate total trip cost."""
    return (days * hotel_rate) + flights

# Pricing specialist agent
pricing_agent = Agent(
    name="pricing_calculator",
    description="Calculate travel costs",  # Tool description for other agents
    model="openai/gpt-4o-mini",
    system_prompt="Answer only with the price. Any text",
    tools=[calculate_cost]
)

# Main travel agent
travel_agent = Agent(
    name="travel_assistant", 
    model="openai/gpt-4o",
    system_prompt="Help plan trips and provide travel advice.",
    tools=[pricing_agent]
)

​
Dynamic Tools

When tool availability depends on runtime conditions (user role, permissions, input parameters), you need dynamic tool resolution. Instead of exposing all tools to the agent, use Timbal’s ToolSet class to resolve which tools are available at runtime. For example, with a role-based ToolSet:
  • Role: admin → Available tools: delete_user, modify_permissions, view_profile
  • Role: user → Available tools: view_profile
The ToolSet checks the role at runtime and returns only the relevant tools. The agent only has access to the tools returned by the ToolSet for that role. Users without admin role won’t see admin tools, preventing the agent from attempting unauthorized actions. See Dynamic Agents for implementation details and examples.

​
Summary

  • Automatic Introspection: Function signatures become tool schemas automatically
  • Enhanced Validation: Pydantic-based parameter validation
  • Execution Flexibility: Support for all Python callable types
  • Better Configuration: Fine-grained parameter control
  • Performance: Concurrent execution and optimized patterns
  • Robustness: Improved error handling and tracing
  • Tool Sets: Dynamic tool resolution
  • Slash Commands: Shortcuts for direct tool invocation
For more advanced patterns, see the Integrations and explore the built-in tools in the Timbal library!