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)
Result
[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