<\/p>\n
AI assistants can talk, but they can’t do things. Everyone knows this problem. OpenAI provided a solution with the Function Calling protocol \u2014 letting LLMs recognize which tools to call during a conversation and having an external service execute them. But the protocol only solves half the problem: who provides these tools? Who executes them? Who guarantees safety?<\/p>\n
<\/p>\n
I built a tool server for my AI assistant (OpenClaw, a.k.a. “Lobster”) called Lobster. It runs on a cloud server, and Lobster calls Lobster’s API through Function Calling, transforming from “just a talker” to “someone who gets things done.” This article isn’t about Lobster’s specific tool list \u2014 it’s about the architectural patterns: the ToolRegistry pattern, Function Calling bridging, security layering, observability, and plugin extension. You can reuse these patterns to build a tool server for any AI assistant.<\/p>\n
<\/p>\n
<\/p>\n
Before an AI assistant can call a tool, it needs to know what tools are available and what parameters each requires. OpenAI defined the Function Calling format \u2014 a JSON Schema containing the tool name, description, and parameter definitions. But your tools are Python functions, CLI commands, HTTP requests \u2014 all in different formats. How do you unify them into a standard format the AI can understand?<\/p>\n
<\/p>\n
Lobster’s approach is the ToolRegistry. The core is simple: when registering each tool, you provide four things \u2014 name, description, parameter definition (JSON Schema), and execution function. Once registered, the ToolRegistry automatically converts all tools into OpenAI Function Calling format.<\/p>\n
<\/p>\n
\nregistry.register(Tool(\n name=\"stock_quote\",\n description=\"Get real-time stock quote\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"code\": {\"type\": \"string\", \"description\": \"Stock code (e.g. sh600519, sz000001, hk00700)\"},\n },\n \"required\": [\"code\"]\n },\n handler=lambda code: investment_tools.get_stock_quote(code),\n category=\"investment\"\n))\n<\/code><\/pre>\n<\/p>\n
After registration, the AI assistant gets the tool list with a single HTTP request:<\/p>\n
<\/p>\n
\ncurl http:\/\/localhost:8000\/tools\/openai\n<\/code><\/pre>\n<\/p>\n
The response is standard Function Calling JSON that can be fed directly to any LLM supporting function calls \u2014 GPT, Claude, DeepSeek, local Ollama models, all of them.<\/p>\n
<\/p>\n
\n{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"stock_quote\",\n \"description\": \"Get real-time stock quote\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"code\": {\"type\": \"string\", \"description\": \"Stock code (e.g. sh600519, sz000001, hk00700)\"}\n },\n \"required\": [\"code\"]\n }\n }\n}\n<\/code><\/pre>\n<\/p>\n
The beauty of this pattern: your tool implementation is a Python function, but the format exposed to the AI is standardized. Adding a new tool is just one register()<\/code> call \u2014 no format conversion worries. The ToolRegistry handles mapping from registration info to Function Calling JSON; you just focus on the business logic.<\/p>\n<\/p>\n
Problem 2: How Does the AI “Call” Your Tools?<\/h2>\n
<\/p>\n
Once the AI assistant knows the tool list and decides during conversation that it needs stock data, it returns a function call instruction:<\/p>\n
<\/p>\n
\n{\"name\": \"stock_quote\", \"arguments\": {\"code\": \"sh600519\"}}\n<\/code><\/pre>\n<\/p>\n
Your server needs to receive this instruction, find the corresponding handler, execute it, and return the result. Lobster uses FastAPI to build an API server where each registered tool is automatically mapped to an execution endpoint:<\/p>\n
<\/p>\n
\ncurl -X POST http:\/\/localhost:8000\/tools\/stock_quote\/execute \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"code\": \"sh600519\"}'\n<\/code><\/pre>\n<\/p>\n
The ToolRegistry does three things upon receiving a request: looks up the registered handler, executes it, and returns the result. Lookup is O(1) by name index, execution is a direct Python function call, and the return is in unified JSON format.<\/p>\n
<\/p>\n
The complete interaction chain: LLM identifies intent \u2192 generates function call \u2192 Lobster API receives it \u2192 ToolRegistry looks up and executes \u2192 result returned to LLM \u2192 LLM organizes a response using real data. Throughout the process, the user only converses with the AI assistant \u2014 tool calls are transparent.<\/p>\n
<\/p>\n
A design choice here: your API server could also expose just a single unified \/execute<\/code> endpoint without routing by tool name. Lobster chose per-tool-name routing (\/tools\/{tool_name}\/execute<\/code>) because it makes per-tool API call logs cleaner \u2014 debugging instantly reveals which tool was called. If you don’t have many tools, a unified endpoint works fine too.<\/p>\n<\/p>\n
Problem 3: Letting AI Do Things Without Letting It Do Anything Reckless<\/h2>\n
<\/p>\n
This is the most easily overlooked problem. Your AI assistant can now read\/write files, execute commands, make HTTP requests \u2014 which means it can also accidentally delete files, run dangerous commands, or request internal network addresses. When giving AI execution capabilities on a cloud server, the security boundary is non-negotiable.<\/p>\n
<\/p>\n
Lobster adds a security validation layer before every tool execution, across three dimensions:<\/p>\n
<\/p>\n
Path Security.<\/strong> File operation tools like file_read<\/code> and file_write<\/code> can only access allowed directories. By default, they’re limited to the current working directory. You can extend the allowed scope through configuration, but the AI cannot escape the boundary to read \/etc\/passwd<\/code> or write \/root\/.bashrc<\/code>.<\/p>\n<\/p>\n
Command Security.<\/strong> The run_shell<\/code> tool has a blocklist: rm -rf \/<\/code>, mkfs<\/code>, dd if=<\/code>, fork bombs, chmod 777 \/<\/code>, wget<\/code> \u2014 these dangerous commands are intercepted directly. You can also configure an allowlist mode that only permits pre-approved safe commands.<\/p>\n<\/p>\n
URL Security.<\/strong> http_get<\/code> and http_post<\/code> only allow http\/https protocols and block localhost, 127.0.0.1, and 0.0.0.0 \u2014 preventing the AI from being tricked into requesting internal services on your server (SSRF protection).<\/p>\n<\/p>\n
There’s also a special check for Python code: the run_python<\/code> tool scans for five high-risk patterns before execution \u2014 os.system<\/code>, subprocess<\/code>, eval()<\/code>, exec()<\/code>, import<\/strong><\/code> \u2014 and refuses to execute if any match is found. The calculator tool uses ast.parse<\/code> + operator<\/code> mapping instead of eval()<\/code>, allowing only arithmetic operations.<\/p>\n<\/p>\n
These validations aren’t decorative optional layers \u2014 they’re mandatory checkpoints for every tool execution. The more capable your AI assistant becomes, the more you need to constrain what it can do. Security validation and tool capability should grow together \u2014 for every new tool you add, think about how it could be abused, then add corresponding protections.<\/p>\n
<\/p>\n
Problem 4: How Do You Know What the AI Called and How It Went?<\/h2>\n
<\/p>\n
Your tool server is running on the cloud \u2014 you’re not there watching it. Which tools did the AI call? Which one was the slowest? Which has the highest failure rate? You need to be able to see this information.<\/p>\n
<\/p>\n
Lobster implements two layers of observability:<\/p>\n
<\/p>\n
Execution Statistics.<\/strong> Every tool call is recorded to ~\/.lobster\/stats\/<\/code>, persisted across sessions. Statistics include: total call count, success\/failure counts, average execution time, and recent call history. You can see the most-used tool rankings, the slowest calls, and the tools with the highest error rates. This data helps you decide which tools are worth optimizing and which might have issues.<\/p>\n<\/p>\n
Caching.<\/strong> The ToolRegistry has a built-in LRU cache with TTL expiration. The same stock code won’t trigger repeated requests to the Sina Finance API within one minute \u2014 because market data doesn’t change much in 60 seconds, and cache hit rates directly reduce external API call volume. The cache also tracks statistics: hit rate, cache size, and eviction count.<\/p>\n<\/p>\n
These two layers are complementary: statistics tell you macro trends (which tools are used most, which are slow), and caching gives you micro optimizations (reducing duplicate calls, lowering latency). If you’re building your own tool server, both layers are worth implementing \u2014 it doesn’t need to be complex. A JSON file for stats + an OrderedDict for caching is enough to get started.<\/p>\n
<\/p>\n
Problem 5: How to Add New Tools<\/h2>\n
<\/p>\n
Your AI assistant’s needs will keep changing. Today it only needs stock quotes, tomorrow it might need to read emails, and the day after it might need to call your company’s internal API. The tool server can’t be a closed system \u2014 it needs a low-cost extension mechanism.<\/p>\n
<\/p>\n
Lobster provides two layers of extension:<\/p>\n
<\/p>\n
Registration Extension.<\/strong> Adding a new tool is a single line of registry.register()<\/code>. You write a handler function in any Python module, call register, and the ToolRegistry automatically includes it in the Function Calling format. No need to modify API server code, no need to manually write JSON Schema \u2014 the parameter definitions provided at registration are automatically converted.<\/p>\n<\/p>\n
Plugin Extension.<\/strong> ~\/.lobster\/plugins\/*\/plugin.py<\/code> is auto-loaded. You create a directory, put a plugin.py file in it, define your tools, and the next time Lobster starts, they’re automatically discovered and registered. A template generator helps you quickly create plugin skeletons.<\/p>\n<\/p>\n
The difference between these two layers: registration extension is for tools you develop yourself (you know where the code is, just import it directly). Plugin extension is for tools contributed by others or tools you want to isolate (independent directory, not coupled to the main code). Your project might only need registration extension, but retaining the plugin mechanism means you can add third-party tools with zero cost in the future.<\/p>\n
<\/p>\n
About MCP<\/h2>\n
<\/p>\n
You may have noticed that Anthropic has introduced MCP (Model Context Protocol), which is becoming a new trend in tool integration. Cursor, VS Code, and various agent frameworks are adopting MCP. What’s the relationship with Function Calling?<\/p>\n
<\/p>\n
MCP and Function Calling solve the same problem \u2014 letting AI call external tools. But the scenarios differ. MCP is designed for IDE and local tool integration \u2014 AI agents connect to local tool servers through the MCP protocol, suited for development scenarios. Function Calling is designed for cloud AI assistants \u2014 LLMs generate tool call instructions in the conversation flow, executed by your server, suited for assistants deployed in the cloud.<\/p>\n
<\/p>\n
Lobster uses the Function Calling format because it runs on a cloud server, and Lobster is also in the cloud. That’s the right choice. But if you’re doing IDE integration or local agents, MCP is the more appropriate protocol.<\/p>\n
<\/p>\n
The good news: the ToolRegistry pattern is protocol-agnostic. Your tool registration, security validation, caching, and statistics architecture layers don’t depend on the specific Function Calling format. Switching to MCP, you only need to change one layer \u2014 from Function Calling JSON to MCP Tool definition format \u2014 while all the handlers, security validation, caching, and statistics underneath are fully reusable. The architectural thinking is universal; the protocol format is replaceable.<\/p>\n
<\/p>\n
Architecture Summary<\/h2>\n
<\/p>\n
Tying the five problems above together, Lobster’s architecture looks like this:<\/p>\n
<\/p>\n
The Tool Registration Layer<\/strong> (ToolRegistry) centrally manages metadata and execution functions for all tools, automatically converting them into a standard format LLMs can understand. The API Server Layer<\/strong> (FastAPI) maps each registered tool to an HTTP endpoint, allowing the AI assistant to call them over the network. The Security Validation Layer<\/strong> performs three-dimensional checks (path, command, URL) before every execution, ensuring the AI can do things without doing reckless things. The Observability Layer<\/strong> records execution statistics and cache data, giving you control over every tool call the AI makes. The Extension Layer<\/strong> adds new tools through both registration and plugin mechanisms, ensuring the toolset can continuously grow.<\/p>\n<\/p>\n
These five layers are each independent \u2014 you can adopt them as needed. If you only need the minimal setup: one ToolRegistry + one FastAPI server is enough. Security validation and caching can be added later. The plugin system can be skipped. What matters first is getting the “AI call \u2192 tool execution \u2192 result return” chain working, then gradually hardening it.<\/p>\n
<\/p>\n
Building a tool server for an AI assistant \u2014 the core isn’t the tools themselves, but the architecture. Your toolset will change \u2014 today it’s stocks and code analysis, tomorrow it might be email and calendar. But the ToolRegistry pattern, security layering, observability, and extension mechanisms \u2014 these architectural layers hold steady regardless of how your tools evolve.<\/p>\n
<\/p>\n
Source Code Navigation<\/h2>\n
<\/p>\n
\n\n\nArchitecture Layer<\/td>\n Source File<\/td>\n Description<\/td>\n<\/tr>\n<\/thead>\n \n\nTool Registration<\/td>\n tools.py<\/a><\/td>\n ToolRegistry, 14 built-in tools, security validation<\/td>\n<\/tr>\n \nAPI Server<\/td>\n api_cmd.py<\/a><\/td>\n FastAPI endpoints, OpenAI Function Calling format<\/td>\n<\/tr>\n \nSecurity Validation<\/td>\n tools.py<\/a><\/td>\n validate_path \/ validate_command \/ validate_url \/ _check_python_dangerous<\/td>\n<\/tr>\n \nExecution Statistics<\/td>\n stats.py<\/a><\/td>\n ToolStatsTracker, persisted statistics<\/td>\n<\/tr>\n \nCaching<\/td>\n cache.py<\/a><\/td>\n LRU cache, TTL expiration, hit rate stats<\/td>\n<\/tr>\n \nFinancial Tools<\/td>\n investment.py<\/a><\/td>\n stock_quote and investment tool registration<\/td>\n<\/tr>\n \nSerena Integration<\/td>\n serena_client.py<\/a><\/td>\n Code intelligence framework integration<\/td>\n<\/tr>\n \nMemory Store<\/td>\n memory_store.py<\/a><\/td>\n TF-IDF + Levenshtein fuzzy search<\/td>\n<\/tr>\n \nPlugin System<\/td>\n plugin.py<\/a><\/td>\n Auto-discovery and loading of custom plugins<\/td>\n<\/tr>\n \nConfiguration<\/td>\n config.py<\/a><\/td>\n .env loading, LobsterConfig<\/td>\n<\/tr>\n \nLLM Client<\/td>\n llm_client.py<\/a><\/td>\n EnhancedLLMClient, conversation management, caching, retry<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/p>\n