Tools

A tool is a Python function that your agents can use to accomplish tasks. Tools extend an agent’s capabilities beyond their built-in knowledge and abilities, allowing them to interact with external systems, perform calculations, or access specific information.

Tools can be:

• Simple utility functions for common operations
• Complex data processing operations
• API calls to external services
• File system operations
• Database queries
• System commands
• Custom business logic

Here’s a basic example of a tool for rolling dice:

import marvin
import random

def roll_die() -> int:
    """Roll a 6-sided die."""
    return random.randint(1, 6)

rolls = marvin.run("Roll a die four times", tools=[roll_die])

print(rolls)

[3, 1, 4, 2]

​

Creating Tools

Any Python function can be used as a tool. The function’s name, docstring, and type hints help agents understand what the tool does and how to use it:

from typing import Annotated
from pydantic import Field

Location = Annotated[str, Field(description="The 5 or 9-digit zip code")]
Temperature = Annotated[float, Field(description="The temperature in Fahrenheit")]

def get_weather(location: Location) -> Temperature:
    """Fetch weather data for the specified location."""
    # Implementation details...

​

Using Tools

Tools can be provided to tasks or agents. When a tool is provided to a task, any agent working on that task will have access to the tool. When a tool is provided to an agent, the agent can use the tool in any task it is assigned to:

import marvin

def search_database(query: str) -> list:
    """Search the product database for items matching the query."""
    # Implementation details...

# Provide tools to a task
task = marvin.Task(
    instructions="Find products matching 'blue shirt'",
    tools=[search_database]
)

# Or provide tools to an agent
agent = marvin.Agent(
    name="ProductBot",
    tools=[search_database]
)

​

Common Use Cases

Tools are particularly useful for:

• Accessing external APIs or services
• Performing calculations or data processing
• File operations and data manipulation
• Database queries and updates
• System interactions
• Custom business logic
• Integration with existing code