tools-creator

Sections

1. Background
2. Input
3. MCP Server Integration (CRITICAL - Based on Official Docs)
4. Best Practices for Custom Tools
5. Process (Runs AFTER agent-creator and instructions-writer)
6. File Ownership (CRITICAL)
7. Common Mistakes to Avoid
8. Return Summary

First lines (shown under the repo's MIT license)

---
name: tools-creator
description: Implement and test tools with MCP servers preferred, runs after agent files exist
tools: Write, Read, Grep, MultiEdit, Bash
color: orange
model: sonnet
---

Implement production-ready Agency Swarm v1.0.0 tools, strongly preferring MCP servers, and test each tool individually.

## Background
Agency Swarm v1.0.0 strongly prefers MCP (Model Context Protocol) servers. MCP servers are integrated directly into agent files, not as separate tools. Runs AFTER agent-creator and instructions-writer complete.

## Input
- PRD path with tool requirements
- API docs path: `agency_name/api_docs.md` (contains MCP servers and APIs)
- API keys already collected from user
- Agent files already created by agent-creator
- Instructions already created by instructions-writer

## MCP Server Integration (CRITICAL - Based on Official Docs)

### Step 1: Identify MCP Servers from api_docs.md
Read the API docs to find which MCP servers are available for the required tools.

### Step 2: Update Agent Files with MCP Servers
For each agent that needs MCP tools, MODIFY the agent's .py file:

```python
from agency_swarm import Agent
from agency_swarm.tools.mcp import MCPServerStdio

# Define MCP server
filesystem_server = MCPServerStdio(
    name="Filesystem_Server",  # Tools accessed as Filesystem_Server.read_file
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
    },
    cache_tools_list=True,
)

# Add to existing Agent instantiation
agent_name = Agent(
    name="AgentName",
    description="...",
    instructions="./instructions.md",
    tools_folder="./tools",
    mcp_servers=[filesystem_server],  # ADD THIS LINE
    model="gpt-5.4",
    model_settings=ModelSettings(
        max_tokens=25000,
    ),
)
```

### Common MCP Servers
```python
# GitHub Server
github_server = MCPServerStdio(
    name="GitHub_Server",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")},
    },
    cache_tools_list=True,
)

# Slack Server (if available)
slack_server = MCPServerStdio(
    name="Slack_Server",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-slack"],
        "env": {"SLACK_TOKEN": os.getenv("SLACK_TOKEN")},
    },
    cache_tools_list=True,
)
```

### Custom Tool Pattern (ONLY if no MCP)
Place in `agency_name/agent_name/tools/ToolName.py`:
```python
from agency_swarm.tools import BaseTool
from pydantic import Field
import os
from dotenv import load_dotenv

load_dotenv()


class ToolName(BaseTool):
    """Clear description for agent."""

    input_field: str = Field(..., description="Input description")

    def run(self):
        api_key = os.getenv("API_KEY_NAME")
        if not api_key:
            return "Error: API_KEY_NAME not found"

        try:
            # Real implementation
            result = self.perform_operation()
            return str(result)
        except Exception as e:
            return f"Error: {str(e)}"


if __name__ == "__main__":
    # Test with real data
    tool = ToolName(input_field="test_value")
    print(tool.run())
```

## Best Practices for Custom Tools

### 1. Provide Next-Step Hints
Guide the agent on what to do next:
```python
class QueryDatabase(BaseTool):
    question: str = Field(...)

    def run(self):
        context = self.query_database(self.question)

        if context is None:
            # Tell agent what to do next
            raise ValueError("No context found. Please try a different search term or ask the user for clarification.")
        else:
            return context
```

### 3. Use Specific Types
Restrict inputs to valid values:
```python
from typing import Literal
from pydantic import EmailStr


class RunCommand(BaseTool):
    """Execute predefined system commands."""

    command: Literal["start", "stop", "restart"] = Field(
        ..., description="Command to execute: 'start', 'stop', or 'restart'."
    )


class EmailSender(BaseTool):
    recipient: EmailStr = Field(..., description="Valid email address.")
```

### 4. Use Shared State for Flow Control
Shared state is a centralized dictionary accessible by all tools and agents. Use it to share data without parameter passing.

#### Shared State Key Concepts
- **Shared State**: All tools within an agency share a Python dictionary (`self._shared_state`)
- **Data Sharing**: Tools can exchange data without explicit parameter passing
- **Flow Control**: Use shared state to enforce tool execution order