Tools

Tools extend agent capabilities by allowing them to interact with external systems, perform calculations, and access data.

MCP-First Design

Every tool in AA Kit follows the Model Context Protocol (MCP) specification. This means any function you write is automatically compatible with Claude Desktop, other MCP clients, and can be shared across agents.

How Tools Work

1

Function Definition

You write a regular Python function with type hints and a docstring.

2

Automatic Conversion

AA Kit converts your function to an MCP-compatible tool with full metadata.

3

Agent Integration

The agent can discover and use the tool based on its description and parameters.

4

Intelligent Usage

The agent decides when and how to use tools based on the task at hand.

Creating Tools

Simple Function Tool

python
from aakit import Agent

# Define a simple tool
def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    # Your weather API logic here
    return f"The weather in {location} is sunny and 72°F"

# Create agent with the tool
agent = Agent(
    name="weather_assistant",
    instruction="You help users with weather information",
    model="gpt-4",
    tools=[get_weather]  # Function automatically converted to MCP tool
)

# Agent can now use the tool
response = await agent.chat("What's the weather in San Francisco?")

Tool with Type Hints

python
from typing import List, Dict
from aakit import Agent, tool

# Use the @tool decorator for enhanced metadata
@tool(
    description="Search our product database",
    returns="List of matching products with details"
)
def search_products(
    query: str,
    category: str = None,
    max_price: float = None
) -> List[Dict]:
    """
    Search for products in our catalog.
    
    Args:
        query: Search term
        category: Optional category filter
        max_price: Optional maximum price filter
    
    Returns:
        List of products matching the criteria
    """
    # Your search logic here
    results = []
    # ... search implementation ...
    return results

agent = Agent(
    name="shop_assistant",
    instruction="You help customers find products",
    model="gpt-4",
    tools=[search_products]
)

Async Tools

python
import asyncio
from aakit import Agent

# Async tools for I/O operations
async def fetch_data(url: str) -> dict:
    """Fetch data from an API endpoint."""
    # Async HTTP request
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

async def process_data(data: dict) -> str:
    """Process fetched data asynchronously."""
    # Async processing
    await asyncio.sleep(1)  # Simulate processing
    return f"Processed {len(data)} items"

agent = Agent(
    name="data_processor",
    instruction="You fetch and process data efficiently",
    model="gpt-4",
    tools=[fetch_data, process_data]
)

Agent as Tool

python
from aakit import Agent

# Create specialized agents
researcher = Agent(
    name="researcher",
    instruction="You research topics thoroughly",
    model="gpt-4",
    tools=[web_search, extract_content]
)

writer = Agent(
    name="writer",
    instruction="You write engaging content",
    model="claude-3"
)

# Use agents as tools for another agent
editor = Agent(
    name="editor",
    instruction="You coordinate research and writing",
    model="gpt-4",
    tools=[researcher, writer]  # Agents as tools!
)

# The editor can now delegate tasks
response = await editor.chat(
    "Create an article about quantum computing"
)

External Tool Integration

python
from aakit import Agent

# Connect to external MCP tools
agent = Agent(
    name="integrated_assistant",
    instruction="You use various external tools",
    model="gpt-4",
    tools=[
        "http://localhost:8080",  # Another MCP server
        "mcp://calculator-service",  # MCP service
        my_local_function,  # Local function
    ]
)

# Agent can seamlessly use all tools
response = await agent.chat(
    "Calculate the compound interest and fetch market data"
)

Tool Best Practices

Function Design

  • ✓Use clear, descriptive function names
  • ✓Add comprehensive docstrings
  • ✓Include type hints for all parameters
  • ✓Return structured data (dict, list)

Performance Tips

  • ✓Use async functions for I/O operations
  • ✓Implement proper error handling
  • ✓Add input validation
  • ✓Cache expensive operations

Tool Metadata

python
from aakit import tool

@tool(
    description="Calculate compound interest",
    parameters={
        "principal": {"type": "number", "description": "Initial amount"},
        "rate": {"type": "number", "description": "Annual interest rate"},
        "time": {"type": "number", "description": "Time period in years"},
    },
    returns="Calculated compound interest amount"
)
def calculate_compound_interest(
    principal: float,
    rate: float,
    time: int
) -> float:
    """Calculate compound interest."""
    return principal * (1 + rate/100) ** time

Tool Categories

Data Tools

  • • Database queries
  • • API integrations
  • • File operations
  • • Data transformations

Computation Tools

  • • Mathematical operations
  • • Statistical analysis
  • • Machine learning
  • • Image processing

Integration Tools

  • • External services
  • • Other agents
  • • MCP servers
  • • Web scraping

Security Considerations

  • • Validate all tool inputs to prevent injection attacks
  • • Use environment variables for sensitive data
  • • Implement rate limiting for expensive operations
  • • Log tool usage for audit trails

Advanced Patterns

Tool Composition

Tools can call other tools, creating powerful compositions:

fetch_data() → process_data() → generate_report()

Dynamic Tool Loading

Load tools based on context or user permissions:

agent.add_tool(admin_tool) if user.is_admin else None

Next Steps

Learn how agents can persist conversation context with memory systems.

Continue to Memory →