Tools

Tools are functions that agents can call to interact with the world beyond conversation.

How Tools Work

When an agent has tools enabled:

1. The LLM sees tool definitions in its context
2. It can decide to call tools during a response
3. Maestro executes the tool and returns results
4. The LLM incorporates results into its response

User: What's 15% tip on $47.50?

Agent thinking: I should use the calculator tool
Agent calls: calculator("47.50 * 0.15")
Tool returns: 7.125

Agent response: A 15% tip on $47.50 would be $7.13.

Built-in Tools

Utility Tools

Tool	Description	Example
calculator	Evaluate math expressions	calculator("sqrt(144)")
datetime	Get current time with timezone	datetime("America/New_York")

Project Tools

Tool	Description
clone_project	Clone a git repository
switch_project	Change active project
list_projects	List all cloned projects
current_project	Show active project

Agent Management Tools

Tool	Description
create_agent	Create a new dynamic agent
update_agent	Modify agent configuration
list_agents	List all available agents
get_agent	Get agent details
delete_agent	Remove a dynamic agent

Code Execution

Tool	Description
claude_code	Execute coding tasks via Claude Code

The claude_code tool runs Claude Code in the active project directory, allowing file operations, command execution, and git operations.

Enabling Tools

In Agent Configuration

config/my-agent.yaml

tools:
  - calculator
  - datetime
  - clone_project

For Dynamic Agents

You: Give the research-assistant the calculator and datetime tools
Maestro: Updated research-assistant with calculator, datetime tools.

Tool Behavior

Calculator

Evaluates mathematical expressions safely.

Input: "2 + 2"
Output: 4

Input: "Math.sin(Math.PI / 2)"
Output: 1

Input: "sqrt(16) + pow(2, 3)"
Output: 12

Datetime

Returns current time in specified timezone.

Input: "America/New_York"
Output: "2025-01-15T14:30:00-05:00"

Input: "UTC"
Output: "2025-01-15T19:30:00Z"

Input: (no timezone)
Output: Current time in system timezone

Clone Project

Clones a git repository to the projects/ directory.

Input: "https://github.com/user/repo"
Output: "Cloned to repo. This is now your active project."

For private repos, requires GITHUB_TOKEN in environment.

Claude Code

Executes coding tasks in the active project.

Input: "Add a health check endpoint to the Express app"
Output: [Claude Code execution results]

Caution

The claude_code tool executes real commands. Use with appropriate caution, especially in production environments.

Tool Security

• Calculator uses safe evaluation (no arbitrary code execution)
• Project tools operate only within the projects/ directory
• Claude Code respects the active project boundary
• All tool calls are logged for observability

Best Practices

1. Enable only what’s needed: Each tool increases context size
2. Match tools to agent role: Coder gets claude_code, not calculator-only agents
3. Consider security: Some tools have side effects
4. Test tool interactions: Verify agents use tools correctly