# AI Agent Tool Design Patterns: Collaboration Tools

> Discover AI agent tool design patterns for collaboration. Learn how MCP servers transform utility functions into first-class tools for LLM agents via a JSON-RPC-like interface.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: design-patterns
- Published: 2026-08-01

---

**The Collaboration Tools pattern implements a Micro-Control-Protocol (MCP) server that transforms utility functions into first-class tools for LLM agents, enabling standardized discovery and invocation through a JSON-RPC-like interface.**

The `bojieli/ai-agent-book` repository demonstrates this architecture in Chapter 4, where a modular MCP server turns isolated capabilities—like browser automation and human oversight—into composable endpoints. This design allows AI agents to orchestrate complex workflows by calling registered functions through a unified protocol.

## MCP Server Architecture for Collaboration Tools

### Tool Registration with FastMCP

In [`chapter4/collaboration-tools/src/main.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/collaboration-tools/src/main.py), the server initializes with `FastMCP("collaboration-tools")` and registers functions using the `@mcp.tool(...)` decorator. This decorator exposes Python functions as JSON-RPC endpoints that LLMs can discover and invoke dynamically, abstracting away the underlying async implementation.

The server listens on a Unix socket (or TCP port) and routes incoming requests to the appropriate Python function, handling serialization, error capture, and concurrent execution on a single asynchronous event loop.

### Modular Tool Organization

The architecture separates concerns into distinct modules within `src/`. Each module encapsulates a specific capability domain, allowing developers to maintain and test tools independently while the central server aggregates them into a cohesive interface. This modularity ensures that adding browser automation does not affect notification logic or timer scheduling.

## Tool Categories and Implementation

### Browser Automation

The [`browser_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/browser_tools.py) module integrates the *browser-use* library to provide web navigation capabilities. Functions like `browser_navigate` accept parameters such as `url` and `new_tab` defined via **Pydantic** fields, enabling agents to perform research, extract content via `mcp_browser_get_content`, and capture screenshots while maintaining persistent sessions through the `BROWSER_USER_DATA_DIR` environment variable.

### Human-in-the-Loop (HITL)

Implemented in [`hitl_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/hitl_tools.py), this module provides `request_admin_approval` and `request_admin_input` functions. These tools pause agent execution to solicit human judgment on critical decisions or ambiguous inputs, ensuring safety and accuracy during autonomous operations.

### Notification Services

The [`notification_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/notification_tools.py) module supports multi-channel alerts including Email, Telegram, Slack, and Discord. Agents use functions like `mcp_send_telegram_message` to report status updates or request attention when long-running tasks complete, with `chat_id` and message parameters strictly validated.

### Timer and Scheduling

Found in [`timer_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/timer_tools.py), scheduling utilities like `set_recurring_timer` allow agents to create time-based triggers. These integrate with notification tools to implement reminder systems and periodic health checks, accepting `interval_seconds` and message payloads as structured arguments.

### Sub-Agent Orchestration

The [`subagent_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/subagent_tools.py) module manages the lifecycle of specialized worker agents. The `spawn_subagent` function delegates complex sub-tasks—such as extensive data scraping—to isolated processes while the parent agent monitors progress via `get_subagent_status`, retaining overall control without blocking the main reasoning thread.

### Intelligence Utilities

Located in [`intelligence_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/intelligence_tools.py), these higher-level functions provide reasoning helpers for code generation and complex problem solving. They extend the agent's cognitive capabilities beyond simple API calls, offering utilities that leverage LLM fallbacks configured in [`llm_fallback.py`](https://github.com/bojieli/ai-agent-book/blob/main/llm_fallback.py).

## Configuration and Environment Management

The [`config.py`](https://github.com/bojieli/ai-agent-book/blob/main/config.py) module uses **Pydantic** models to load configuration from user-specific directories and environment variables. The system never hard-codes secrets; instead, it reads sensitive values like API keys from `.env` files when present, following security best practices. Environment variables such as `BROWSER_USER_DATA_DIR` configure browser persistence paths without code changes.

## Practical Code Examples

### Browser Navigation

```python
import asyncio
from mcp.client import MCPClient

async def demo_browser():
    client = MCPClient("tcp://localhost:5000")
    result = await client.call(
        "mcp_browser_navigate",
        {"url": "https://github.com/bojieli/ai-agent-book", "new_tab": False}
    )
    print(result)  # → {"success": true, "url": "...", "title": "..."}

asyncio.run(demo_browser())

```

### Scheduling and Notifications

```python
import asyncio
from mcp.client import MCPClient

async def demo_timer():
    client = MCPClient("tcp://localhost:5000")
    await client.call("set_recurring_timer", {"interval_seconds": 3600, "message": "Hourly check‑in"})
    await client.call("mcp_send_telegram_message", {"message": "Timer set!", "chat_id": "12345"})

asyncio.run(demo_timer())

```

### Sub-Agent Delegation

```python
import asyncio
from mcp.client import MCPClient

async def demo_subagent():
    client = MCPClient("tcp://localhost:5000")
    sub_id = await client.call(
        "spawn_subagent",
        {"name": "scraper", "task": "extract all tables from https://example.com"}
    )
    status = await client.call("get_subagent_status", {"subagent_id": sub_id})
    print(status)

asyncio.run(demo_subagent())

```

## Composable Workflow Patterns

The MCP protocol enables agents to chain tools into complex workflows:

- **Navigate → Extract → Summarize:** The agent calls `mcp_browser_navigate` to open a page, uses `mcp_browser_get_content` to extract text, and feeds the result into downstream LLM processing for synthesis.
- **Schedule → Notify:** A `set_timer` call creates a future trigger that invokes `send_telegram_message` upon completion, implementing automated reminder systems without persistent polling.
- **Spawn and Monitor:** The parent agent delegates long-running tasks via `spawn_subagent` while periodically checking `get_subagent_status` to maintain oversight, enabling parallel execution without blocking the main reasoning thread.

## Extensibility and Testing

The design follows a **plug-and-play pattern**: developers add new capabilities by creating a module in `src/`, exposing functions with `@mcp.tool`, and restarting the server. This separation between tool definition and invocation simplifies unit testing—individual modules test in isolation, while integration tests exercise the full JSON-RPC stack through the MCP client.

All tools share a single asynchronous event loop, allowing concurrent execution while errors return as structured JSON objects that enable the agent to recover or escalate to HITL endpoints.

## Summary

- The **MCP server architecture** in `bojieli/ai-agent-book` standardizes how LLM agents discover and invoke tools through a JSON-RPC interface defined in [`main.py`](https://github.com/bojieli/ai-agent-book/blob/main/main.py).
- **Six modular categories**—browser automation, HITL, notifications, timers, sub-agents, and intelligence utilities—provide comprehensive agent capabilities through dedicated modules.
- **Pydantic-based configuration** in [`config.py`](https://github.com/bojieli/ai-agent-book/blob/main/config.py) ensures secure, environment-aware settings without hard-coded secrets, respecting variables like `BROWSER_USER_DATA_DIR`.
- **Composable workflows** allow agents to chain tools like `browser_navigate`, `set_recurring_timer`, and `spawn_subagent` into autonomous task pipelines.
- The **plug-and-play registration** system via `@mcp.tool` decorators enables rapid extension without modifying core server logic, supporting both unit and integration testing strategies.

## Frequently Asked Questions

### What is the Micro-Control-Protocol (MCP) in AI agent collaboration tools?

MCP is a standardized protocol that exposes Python functions as JSON-RPC endpoints, allowing LLM agents to discover and invoke tools through a consistent interface. In the `bojieli/ai-agent-book` implementation, the `FastMCP` server registers decorated functions from [`main.py`](https://github.com/bojieli/ai-agent-book/blob/main/main.py) and handles serialization, error management, and concurrent execution on a single async event loop, enabling agents to interact with external systems through simple JSON payloads.

### How does the browser automation tool handle complex navigation?

The [`browser_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/browser_tools.py) module leverages the *browser-use* library to provide functions like `browser_navigate` and `mcp_browser_get_content`. These accept structured arguments (e.g., `url`, `new_tab`) defined via Pydantic `Field` definitions, enabling agents to perform multi-step web research while maintaining session state through configurable user data directories specified in environment variables.

### Can developers add custom tools to the existing MCP server?

Yes. Developers create a new Python module in `chapter4/collaboration-tools/src/`, implement an async function with typed parameters using Pydantic `Field` definitions, and decorate it with `@mcp.tool()`. The server automatically registers new tools on startup, making them immediately available to any MCP-compliant client without modifying the core registration logic in [`main.py`](https://github.com/bojieli/ai-agent-book/blob/main/main.py) beyond standard module imports.

### How does the human-in-the-loop mechanism function during autonomous execution?

When an agent encounters uncertain situations or requires privileged actions, it calls `request_admin_approval` or `request_admin_input` from [`hitl_tools.py`](https://github.com/bojieli/ai-agent-book/blob/main/hitl_tools.py). These functions suspend the async operation and wait for human response through the MCP interface, returning the user's decision or input as structured JSON that the agent incorporates into its next reasoning step, ensuring safety and accountability without breaking the tool contract.