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

> Learn to design effective AI agent tool descriptions using ACI principles. Write JSON schemas from the agent's view to reduce hallucination and ensure reliable tool use.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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:

```json
{
  "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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/perception-tools/search_web.py):

```python
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`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/perception-tools/search_web.py) |
| **Execution** | State-changing actions | [`chapter4/execution-tools/execute_command.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/execution-tools/execute_command.py) |
| **Collaboration** | Inter-agent communication | [`chapter4/collaboration-tools/notify_slack.py`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/book/chapter4.md) — Narrative explanation of ACI philosophy and MCP basics
- [`book-en/chapter4.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter4.md) — English-language version with identical technical content (lines 96-104)
- [`chapter4/perception-tools/search_web.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/perception-tools/search_web.py) — Reference perception tool implementation
- [`chapter4/execution-tools/execute_command.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/execution-tools/execute_command.py) — Sandboxed execution tool with path validation
- [`chapter4/collaboration-tools/notify_slack.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter4/collaboration-tools/notify_slack.py) — Cross-agent notification tool
- [`scripts/mcp_server.py`](https://github.com/bojieli/ai-agent-book/blob/main/scripts/mcp_server.py) — Minimal MCP server handling discovery and invocation endpoints
- [`README.md`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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.