ACI Principles for Tool Design: The Agent-Computer Interface Framework

Agent-Computer Interface (ACI) is a design mindset that treats a tool’s API as an interface for the agent, not for a human programmer, comprising three core principles: forms of capability expression, art of tool description, and fidelity of parameter passing.

Designing effective tools for LLM agents requires shifting perspective from human-centric APIs to agent-centric interfaces. According to the bojieli/ai-agent-book repository, the ACI principles for tool design provide a framework for creating APIs that are easy for agents to discover, invoke, and reason about while minimizing the chance of misuse. This approach, detailed in book-en/chapter4.md and introduced in book-en/chapter1.md, distinguishes between how humans and agents interact with software capabilities.

What Is the Agent-Computer Interface?

The Agent-Computer Interface (ACI) refers to the boundary between an LLM agent and its computational environment. Unlike traditional APIs designed for human programmers who can read documentation and handle ambiguity, ACI-optimized tools are structured specifically for agent consumption. As implemented in the ai-agent-book repository, this mindset prioritizes token efficiency, unambiguous intent, and predictable execution to reduce error amplification when the LLM attempts to use external capabilities.

The Three Core ACI Principles for Tool Design

The "Universal Principles of Tool Design" in book-en/chapter4.md distill ACI into three concrete guidelines that govern how capabilities should be exposed, described, and executed.

1. Forms of Capability Expression

The first principle requires deciding whether a capability should be exposed as a dedicated tool, a general executor, or a Skill document. According to lines 37-48 of book-en/chapter4.md, each form represents a trade-off between token cost, flexibility, and reasoning burden:

• Dedicated tools provide a strict JSON schema with explicit parameters. They incur high token costs but offer low ambiguity and strong type safety.
• General executors allow the agent to write code or shell commands (e.g., a Python interpreter). These minimize token usage and maximize flexibility but require the agent to perform more reasoning.
• Skills describe procedural workflows in natural language, making them human-friendly and easy to edit without code changes.

Select the form that balances your security requirements, the agent’s reasoning capabilities, and the complexity of the operation.

2. The Art of Tool Description

The second principle mandates that tool descriptions explicitly tell the model when to use the tool and what it cannot do. As specified in book-en/chapter4.md (lines 69-84), high-quality descriptions must include:

• Concrete parameter examples showing valid input formats
• Clear boundaries and constraints (e.g., "Must be between 1 and 10")
• Real-world invocation examples demonstrating typical use cases

Avoid generic descriptions. A well-designed description prevents the agent from hallucinating capabilities or using the tool in inappropriate contexts, directly reducing error rates in agent workflows.

3. Fidelity of Parameter Passing

The third principle, detailed in lines 87-98 of book-en/chapter4.md, demands fidelity of parameter passing: the agent must see exactly what the tool will receive and return. This principle prohibits:

• Silent input transformations (e.g., automatic path normalization, Unicode quote conversion)
• Hidden parameter injections that the agent did not specify
• Undocumented default values that alter behavior unexpectedly

Any necessary normalization must be explicitly documented in the tool description, ensuring the agent's reasoning about inputs remains accurate and traceable.

Implementing ACI Principles in Code

Below are minimal implementations demonstrating how to apply these ACI principles when defining tools for LLM-agent frameworks such as OpenAI function calling.

Choosing the Right Capability Form

# Dedicated tool – strict schema, high structure

def deploy_app(env: str, version: str) -> str:
    """Deploy `version` to `env` (prod, staging, dev)."""
    ...

# General executor – maximum flexibility, single entry point

def code_interpreter(code: str) -> str:
    """Run arbitrary Python code in a sandbox."""
    ...

# Skill – natural language workflow document

# skills/deploy_app.skill.md

"""
1. Run `npm run build`.
2. Build Docker image: `docker build -t myapp:{version} .`.
3. Push and deploy with `kubectl apply -f k8s.yaml`.
"""

Writing High-Fidelity Tool Descriptions

{
  "name": "web_search",
  "description": "Search the web for up-to-date information. Use when you need facts that may have changed since training.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query, e.g. \"latest OpenAI model release date\"."
      },
      "top_k": {
        "type": "integer",
        "description": "Number of results to return, default 5. Must be between 1 and 10."
      }
    },
    "required": ["query"]
  },
  "examples": [
    {"query": "current UTC time", "top_k": 3},
    {"query": "price of AAPL stock today", "top_k": 1}
  ]
}

Ensuring Parameter Fidelity

import os

def rename_file(old_path: str, new_path: str) -> str:
    """
    Rename a file without any hidden changes.
    
    NOTE: This function does not modify paths (no OS-specific slash conversion).
    If you need path normalization, explicitly handle it before calling.
    """
    # No silent transformations – the agent sees the raw strings exactly.

    os.rename(old_path, new_path)
    return f"Renamed {old_path} → {new_path}"

Summary

• ACI principles for tool design treat the API as an interface for the agent, prioritizing discoverability and predictable execution over human readability.
• Forms of capability expression require selecting between dedicated tools (structured), general executors (flexible), or Skills (procedural) based on token cost and security needs.
• The art of tool description necessitates explicit documentation of when to use the tool, its boundaries, and concrete invocation examples to prevent misuse.
• Fidelity of parameter passing prohibits silent transformations and hidden injections, requiring complete transparency between the agent's intent and the tool's execution.

Frequently Asked Questions

What is the difference between ACI and traditional API design?

Traditional API design optimizes for human developers who can interpret ambiguous documentation and handle implicit behaviors. ACI design optimizes for LLM agents that require explicit schemas, unambiguous descriptions, and predictable parameter handling to minimize reasoning errors and token waste.

When should I use a Skill versus a dedicated tool according to ACI principles?

Use a Skill when the workflow is procedural, frequently changes, or requires human-readable documentation that non-developers can edit. Use a dedicated tool when you need strict type safety, structured inputs, and minimal ambiguity, particularly for operations affecting critical systems or sensitive data.

How do I ensure parameter fidelity in my tool implementations?

Document every transformation that occurs between the agent's output and the tool's execution. If your tool normalizes paths, converts encodings, or injects defaults, explicitly state these behaviors in the description. Never perform silent modifications that the agent cannot anticipate when forming its function call.

Where are the ACI principles documented in the ai-agent-book repository?

The three core principles are detailed in book-en/chapter4.md (lines 37-98), with foundational concepts introduced in book-en/chapter1.md and ecosystem integration discussed in book-en/chapter10.md, which covers how ACI interacts with MCP (Model Context Protocol) and Skill Hubs.

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