agenticx-tool-creator

name	agenticx-tool-creator
description	Guide for creating custom tools in AgenticX including function decorator tools, MCP tool integration, tool registries, and remote tool access. Use when the user wants to create tools for agents, integrate external APIs as tools, build MCP servers, or extend agent capabilities with custom functions.
metadata	{"author":"AgenticX","version":"0.5.0"}

AgenticX Tool Creator

Guide for building tools that extend agent capabilities.

Tool Architecture

AgenticX tools inherit from BaseTool and are consumed by agents during execution. Three approaches exist:

1. Function decorator (@tool) — fastest for simple tools
2. Class-based (extend BaseTool) — for complex or stateful tools
3. MCP remote tools — for external services via Model Context Protocol

Function Decorator Tools

from agenticx.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for information.

    Args:
        query: The search query string.

    Returns:
        Search results as text.
    """
    # implementation
    return f"Results for: {query}"

@tool
def read_file(path: str) -> str:
    """Read contents of a local file."""
    with open(path) as f:
        return f.read()

The @tool decorator reads the function signature and docstring to generate the tool schema automatically. The docstring is the tool description the LLM sees.

Class-Based Tools

For tools needing initialization, state, or complex logic:

from agenticx.core import BaseTool

class DatabaseQuery(BaseTool):
    name = "database_query"
    description = "Query the project database."

    def __init__(self, connection_string: str):
        super().__init__()
        self.conn = connect(connection_string)

    def _run(self, sql: str) -> str:
        return self.conn.execute(sql).fetchall()

Tool Registry

Register and discover tools globally:

from agenticx.core import ToolRegistry

registry = ToolRegistry()
registry.register(search_web)
registry.register(read_file)

# List all registered tools
for t in registry.list_tools():
    print(f"{t.name}: {t.description}")

MCP Integration

AgenticX supports the Model Context Protocol for remote tool access.

Connecting to an MCP Server

from agenticx.protocols import MCPClient

client = MCPClient(server_url="http://localhost:3000")
tools = client.list_tools()

# Use MCP tools like local tools
result = client.call_tool("search", {"query": "AI agents"})

Building an MCP Server

AgenticX agents can be exposed as MCP-compatible services:

from agenticx.protocols import MCPServer

server = MCPServer(host="0.0.0.0", port=3000)
server.register_tool(search_web)
server.register_tool(read_file)
server.start()

Skill-Based Tools

Skills (SKILL.md bundles) are also exposed as tools via SkillTool:

from agenticx.tools.skill_bundle import SkillBundleLoader, SkillTool

loader = SkillBundleLoader()
skill_tool = SkillTool(loader=loader)
# Agents can invoke: skill_tool("list") or skill_tool("read <skill-name>")

Tool Design Guidelines

1. Clear docstrings — the LLM uses the docstring to decide when to call the tool
2. Type hints — always annotate parameters and return types
3. Error handling — return descriptive error messages, don't raise bare exceptions
4. Minimal scope — one tool, one purpose
5. Idempotent when possible — safe to retry without side effects
6. Test independently — verify tools work before attaching to agents

Advanced: Tool Context

Tools can access execution context:

@tool
def contextual_tool(query: str, _context: "ToolContext" = None) -> str:
    """A tool that uses execution context."""
    if _context:
        user = _context.user
        session = _context.session_id
    return f"Processed: {query}"