Designing Tool Descriptions for AI Agents Using ACI Principles: A Complete Guide

Designing tool descriptions for AI agents using ACI (Agent-Computer Interface) principles means writing JSON schemas from the agent's perspective, not the programmer's, to minimize hallucination and maximize reliable tool invocation.

The AI Agent Book by bojieli defines a rigorous architectural framework for building agents that can safely and effectively call external tools. At its heart lies the Agent-Computer Interface (ACI)—a design philosophy that treats tool interfaces as first-class concerns for language models rather than afterthoughts bolted onto traditional APIs. This article walks through the concrete implementation patterns found in book/chapter4.md and the accompanying reference code.

What Is the Agent-Computer Interface (ACI)?

The ACI inverts the traditional API design mindset. Instead of asking "what does the developer need?", it asks "what does the LLM need to understand and invoke this tool correctly?" As documented in book/chapter4.md (lines 96-102), this shift prevents two common failure modes: hallucination (inventing invalid arguments) and misuse (calling the right tool with wrong semantics).

The ACI stack rests on three layers:

• LLM + Context + Tools — the reasoning core with short-term memory and tool definitions
• MCP (Model↔Computer Protocol) — a lightweight JSON-over-HTTP protocol for discovery and invocation
• Tool categories — perception, execution, and collaboration tools, each with schema conventions

Core ACI Design Principles

When designing tool descriptions for AI agents, the repository emphasizes four guiding rules repeated across all language-specific chapters (book-en/chapter4.md, lines 96-104).

1. Granularity Trade-off

A tool should accomplish one meaningful step in an agent's reasoning chain. Too fine-grained forces excessive orchestration; too coarse hides reusable sub-operations. The search_web example in chapter4/perception-tools/search_web.py strikes this balance: one call fetches multiple results, but doesn't attempt full research synthesis.

2. Generality Over Specialization

Prefer general-purpose primitives. A code interpreter tool serves diverse tasks; a "calculate mortgage payment" tool serves one. General tools reduce the total schema surface the LLM must manage.

3. Description Conventions

Every tool publishes a strict JSON schema with three mandatory fields:

• name — short, kebab-case identifier ("search_web", not "SearchWebHandler")
• description — written for the LLM, describing when and why to use the tool
• parameters — full JSON Schema with types, constraints, and defaults

4. Error-Proofing (Poka-yoke)

Schema validation acts as a poka-yoke mechanism—making wrong inputs impossible. Constrain paths to sandbox directories, bound numeric ranges, and require explicit flags for destructive operations.

MCP Tool Schema: The Concrete Contract

The Model↔Computer Protocol defines the exact contract between agent and tool. Below is the canonical structure, matching implementations in chapter4/*-tools/ folders:

{
  "name": "search_web",
  "type": "perception",
  "description": "Search the internet for a query and return the top result snippet.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query, e.g. \"latest LLM research\"."
      },
      "top_k": {
        "type": "integer",
        "default": 1,
        "minimum": 1,
        "maximum": 5,
        "description": "Number of results to return."
      }
    },
    "required": ["query"]
  }
}

Key schema decisions that support ACI principles:

• Short, unambiguous names — LLMs can reliably reproduce them
• Inline type annotations — no external references to resolve
• Bounded constraints — minimum, maximum, enum prevent hallucinated values
• Default values — reduce required parameters to the essential minimum

The Tool Lifecycle: Discovery to Execution

According to the source code in scripts/mcp_server.py (or analogous server implementations in chapter4/), an agent interacts with tools through four phases:

Discovery

Agents query GET /tools to fetch available schemas. Proactive discovery—requesting only relevant tool subsets—reduces token pressure versus loading all definitions into every prompt.

Selection

The LLM reasons over retrieved schemas, matching current goals against tool descriptions. Clear description fields drive this matching; ambiguous descriptions cause selection errors.

Invocation

A POST /invoke call carries the tool name and filled arguments. The MCP server validates against the registered schema before executing underlying logic.

Result Integration

Structured JSON responses feed back into the LLM's context window, enabling iterative multi-tool workflows.

Complete Implementation Example

This runnable Python client demonstrates the full lifecycle, mirroring the reference implementation in chapter4/perception-tools/search_web.py:

import json
import requests

MCP_URL = "http://localhost:8000"

# 1. Register a new tool (admin/initialization step)

tool_schema = {
    "name": "search_web",
    "type": "perception",
    "description": "Search the internet for a query and return the top result snippet.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Search terms to find relevant web content."
            },
            "top_k": {
                "type": "integer",
                "default": 1,
                "minimum": 1,
                "maximum": 5,
                "description": "Number of result snippets to return (1-5)."
            }
        },
        "required": ["query"]
    }
}
requests.post(f"{MCP_URL}/tools", json=tool_schema).raise_for_status()

# 2. Discover available tools (agent runtime)

response = requests.get(f"{MCP_URL}/tools")
available_tools = response.json()
print(f"Loaded {len(available_tools)} tools: {[t['name'] for t in available_tools]}")

# 3. Invoke tool with LLM-populated arguments

invocation = {
    "name": "search_web",
    "arguments": {
        "query": "agent-computer interface design patterns",
        "top_k": 3
    }
}
result = requests.post(f"{MCP_URL}/invoke", json=invocation).json()
print(f"Search output: {result['output']}")

Each phase illustrates ACI principles in action: registration with agent-centric descriptions, discovery saving token budget, and schema validation preventing malformed calls.

Tool Categories in the Repository

The AI Agent Book organizes reference implementations into three functional families:

Category	Purpose	Example File
Perception	Read-only data access	chapter4/perception-tools/search_web.py
Execution	State-changing actions	chapter4/execution-tools/execute_command.py
Collaboration	Inter-agent communication	chapter4/collaboration-tools/notify_slack.py

Each follows identical schema conventions but varies in safety requirements. Execution tools typically include sandbox path constraints; collaboration tools require authentication tokens in parameters.

Key Source Files and Their Roles

• book/chapter4.md — Narrative explanation of ACI philosophy and MCP basics
• book-en/chapter4.md — English-language version with identical technical content (lines 96-104)
• chapter4/perception-tools/search_web.py — Reference perception tool implementation
• chapter4/execution-tools/execute_command.py — Sandboxed execution tool with path validation
• chapter4/collaboration-tools/notify_slack.py — Cross-agent notification tool
• scripts/mcp_server.py — Minimal MCP server handling discovery and invocation endpoints
• README.md — Project overview including Agent = LLM + Context + Tools formulation (lines 10-12)

Summary

Designing tool descriptions for AI agents using ACI principles requires:

• Agent-centric perspective — write descriptions for LLM comprehension, not human documentation
• Strict JSON Schema — enforce types, bounds, and constraints at the protocol level
• MCP standardization — use /tools discovery and /invoke execution for interoperability
• Poka-yoke validation — make incorrect invocations impossible through schema design
• Granular generality — tools should be reusable yet complete single reasoning steps

These patterns, established in bojieli's AI Agent Book and implemented across chapter4/ reference code, provide a reproducible foundation for reliable agent tool use.

Frequently Asked Questions

What makes ACI different from traditional API design?

Traditional APIs optimize for developer ergonomics—comprehensive documentation, flexible endpoints, rich error messages. ACI optimizes for LLM reliability: concise descriptions, strict schemas, and validation that prevents malformed calls before execution. As noted in book/chapter4.md, this perspective shift reduces hallucination by treating the agent as the primary interface consumer.

How does proactive tool discovery save tokens?

Instead of embedding dozens of tool descriptions in every prompt, agents query GET /tools to retrieve only relevant schemas. This externalizes static definitions from the LLM's context window, preserving token budget for reasoning. The MCP server's response caching further reduces redundant data transfer.

Why are bounded constraints critical in tool parameters?

Unbounded parameters invite hallucination: an LLM might invent top_k=999 or a non-existent file path. JSON Schema constraints (minimum, maximum, pattern, enum) act as guardrails that fail validation before dangerous or nonsensical values reach implementation code. This is the poka-yoke principle in practice.

Can existing REST APIs be retrofitted for ACI?

Partially. Wrapping traditional APIs with MCP adapters requires rewriting descriptions for LLM comprehension and adding strict schema validation. The repository's execution and collaboration tool examples show this pattern: underlying services (shell commands, Slack) are exposed through ACI-compliant MCP layers with sanitized inputs and structured outputs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}