Agent-First Tool API: A Semantic Interface Paradigm for Enterprise AI Agent Systems

This paper proposes and validates the "Agent-First Tool API" paradigm, which replaces traditional human-oriented CRUD interfaces with a semantic six-verb protocol and structured decision-support metadata to significantly enhance autonomous agent task success rates and error recovery in enterprise production systems.

The Gist

Imagine you are trying to give a complex instruction to a very smart, but slightly literal, robot assistant.

The Old Way (The "CRUD" Problem):
Right now, most enterprise software (like the systems banks or stores use) is built for humans. If you want a human to "find the downtown branch that opened last month," they can look at a map, read a sign, and figure it out.

But if you ask a robot to do this using today's standard software interfaces, it's like asking the robot to fill out a tax form where it must know the exact 10-digit ID number of the branch before it can even start. If the robot guesses the ID wrong, the system just says "Error 404" and stops. The robot has to guess again, get another error, and eventually give up or ask a human for help. This is what the paper calls the "CRUD" mismatch: the software expects exact IDs and precise data, but the AI starts with a vague, natural-language goal.

The New Way (Agent-First Tool APIs):
The authors propose a new way of designing these tools specifically for AI agents. Instead of a rigid form, they treat the tool like a helpful human assistant who knows how to handle ambiguity.

Here is how their "Six-Verb" system works, using the analogy of a Travel Agent:

1. Semantic Search (The "What do you mean?" phase):
   • Old Way: You must say "Book flight to JFK."
   • New Way: You say, "Book a flight to the airport near Times Square." The tool doesn't panic; it searches its database, finds three airports near Times Square, and says, "I found JFK, LaGuardia, and Newark. Which one did you mean?"
2. Resolve Candidates (The "Clarification" phase):
   • The AI picks the right one (JFK) from the list. The tool confirms, "Got it, JFK."
3. Preview Action (The "Dry Run" phase):
   • Before actually booking the ticket (which costs money), the tool shows a draft: "Here is what I'm about to do: Book a flight to JFK for $500. Is this okay?" This prevents mistakes before they happen.
4. Execute Action (The "Do it" phase):
   • Once the AI (or a human manager) says "Yes," the tool actually books the ticket.
5. Verify Result (The "Did it work?" phase):
   • The tool immediately checks its own work: "I just booked the ticket. Let me double-check the database to make sure the confirmation number is real."
6. Recover from Error (The "Plan B" phase):
   • If something goes wrong (e.g., the flight is sold out), the tool doesn't just crash. It says, "That flight is full, but here are three other flights that work. Which one should we try?"

The Safety Net (Governance):
The paper also introduces a strict "security guard" system.

• Dual-Layer Permissions: It checks two things: "Does this AI have the job title to do this?" (Capability) AND "Is this AI allowed to touch this specific store's data?" (Scope).
• Dynamic Risk: If the AI tries to do something small (like checking a ticket), it goes right through. If it tries to do something big (like deleting 500 records or changing prices for a whole brand), the system automatically pauses and asks a human manager for approval before proceeding.

The Results:
The authors tested this in a real-world system with 85 different tools (like managing work orders, training staff, or fixing equipment).

• Success Rate: The new system solved 88% of tasks, while the old system only solved 64%.
• Less Human Help: The new system needed human intervention only 6% of the time, compared to 22% for the old system.
• Fewer Mistakes: The AI made far fewer "hallucinations" (guessing wrong IDs) because the tool helped it find the right ID first.

The Trade-off:
The new system takes a little more time and uses more "computing power" (tokens) for each individual step because it does all these extra checks (searching, previewing, verifying). However, because it fails less often and doesn't get stuck in loops of guessing, the total time to finish a whole job is actually faster and much more reliable.

In Summary:
The paper argues that to make AI agents truly useful in businesses, we can't just give them the same tools we use for humans. We need to redesign the tools to be conversational, self-correcting, and safety-conscious, turning the AI from a "blind guesser" into a "supervised professional."

Technical Summary

Technical Summary: Agent-First Tool APIs

1. Problem Statement

The paper identifies a critical architectural mismatch between the emerging capabilities of Large Language Model (LLM) agents and the legacy design of enterprise software interfaces. While LLM agents are rapidly becoming primary operators of enterprise systems, the APIs they invoke remain designed for human-driven User Interfaces (UIs).

The authors argue that traditional CRUD (Create, Read, Update, Delete) APIs rely on five assumptions that collapse when the caller is an autonomous agent rather than a human:

1. Exact Parameters: CRUD assumes callers know precise identifiers (e.g., UUIDs), whereas agents start with natural language goals requiring disambiguation.
2. Renderable Data: REST APIs return raw JSON for UI rendering, lacking the decision-support metadata (confidence scores, provenance) agents need for reasoning.
3. Single Round-Trip: CRUD assumes one request per action, while agents operate in multi-turn reasoning loops.
4. Static Permissions: Traditional access control binds to the user, lacking a second layer for what a tool is allowed to do independently of user UI entitlements.
5. Opaque Errors: HTTP status codes (e.g., 400 Bad Request) inform human developers but provide no structured recovery strategies for agents.

Existing frameworks (e.g., LangChain, AutoGPT) and transport standards (e.g., Model Context Protocol/MCP) address orchestration and discovery but leave the tool interface itself as a "black box" conforming to legacy conventions, forcing developers into brittle prompt engineering and ad-hoc error handling.

2. Methodology and Design Paradigm

The paper proposes the Agent-First Tool API paradigm, which reconceives tool interfaces as "goal-achievement protocols" rather than "form-submission endpoints." The design is implemented within a production multi-tenant SaaS work-order management system, spanning 85 tools across 6 business domains.

A. Six-Verb Semantic Protocol

The core interaction model decomposes tool usage into a finite-state machine (FSM) consisting of six semantic verbs, structuring every interaction as a reasoning loop:

1. Semantic Search (S): Accepts descriptive, ambiguous, or partial natural language input and returns ranked candidates with relevance scores.
2. Resolve Candidates (R): Handles disambiguation when multiple candidates exist or confidence is low, prompting the agent to select or providing a resolution.
3. Preview Action (P): For state-mutating tools, provides a dry-run summary of projected changes and risk assessment before execution.
4. Execute Action (E): Performs the mutation within a transactional boundary, enforcing idempotency via caller-supplied keys.
5. Verify Result (V): Post-execution, re-reads the state to confirm it matches the agent's original intent.
6. Recover from Error (C): Returns structured recovery guidance (candidates, suggestions) rather than opaque error codes.

Not all tools require all six verbs; read-only tools typically implement only Search (and optionally Resolve), while high-risk tools implement the full cycle.

B. Normalized Tool Contract (NTC)

To replace raw JSON responses, the authors introduce the NTC, a standardized response specification that augments every tool output with:

• Decision Support: A confidence score (0–1) to guide planning decisions.
• Evidential Provenance: A structured evidence array detailing match counts, sources, and logic applied.
• Action Continuity: A next_actions array suggesting logical follow-up tools to reduce the planner's search space.
• Result Traceability: result_refs containing typed entity identifiers for downstream consumption.

The system employs a Bayesian sliding-window calibration mechanism to adjust static confidence scores based on empirical success rates.

C. Dual-Layer Governance Pipeline

The design introduces a six-layer validation pipeline and a dual-layer permission model:

• Validation Pipeline: Schema Validation → Capability Permission → Object Scope → Dynamic Risk Assessment → Approval Gate → Execution.
• Dual-Layer Permissions: Separates Capability (what a role can invoke) from Object Scope (what data within a hierarchy of Tenant → Brand → Store → User the role can access).
• Dynamic Risk Escalation: Risk levels are adjusted at runtime based on factors such as the number of affected entities, cross-brand operations, or irreversible actions. High-risk operations trigger built-in approval workflows that suspend execution without blocking the agent's thread.

D. Descriptive Input

A defining principle is that tools accept descriptive input (e.g., "downtown branch") and perform internal resolution, shifting the burden from the LLM's probabilistic context window to deterministic backend logic.

3. Key Results

The authors conducted a controlled experiment comparing the Agent-First paradigm against a baseline of traditional CRUD APIs using the same MiniMax-M2.7 LLM and ReAct prompting strategy across 50 tasks.

• Task Success Rate: Increased from 64.0% (CRUD) to 88.0% (Agent-First), a 37.5% improvement.
• Error Recovery: Successful recovery from errors improved by 5.8× (72.7% vs. 12.5%).
• Hallucination Reduction: ID hallucination errors dropped by 85.7% (from 28% to 4%).
• Human Intervention: Required human intervention decreased by 72.7% (from 22% to 6%).
• Efficiency: Despite higher per-call latency and token consumption due to multi-phase protocols, the average number of API calls per task decreased by 33.3% (4.8 to 3.2) because exploratory retry loops were eliminated.
• Net Latency: While individual tool calls took longer (+48.4%), the net task latency decreased by 1.3 seconds on average due to the elimination of failed retry cycles.

4. Significance and Claims

The paper claims that the Agent-First Tool API paradigm is a prerequisite for trustworthy agentic AI in production enterprise environments. Its primary contributions are:

1. Bridging the Paradigm Gap: It addresses the fundamental disconnect between how LLMs reason (natural language, multi-turn, probabilistic) and how traditional APIs behave (exact IDs, single-turn, deterministic).
2. Orthogonality to Transport Standards: The authors emphasize that their work is complementary to standards like the Model Context Protocol (MCP). While MCP solves transport and discovery, Agent-First APIs solve reliability and governability at the application layer.
3. Enterprise-Grade Governance: It demonstrates that autonomous execution can be safely managed without external orchestration layers by embedding governance (permissions, risk assessment, approval) directly into the tool interface.
4. Practical Viability: The validation across 85 tools in a live SaaS environment proves that the paradigm is architecturally sound and effective at reducing ambiguity-induced failures without requiring "superhuman" LLM capabilities.

The authors conclude that while the approach incurs engineering overhead (maintaining dual API surfaces), the trade-off is justified by the dramatic reduction in failure modes and the enablement of truly autonomous enterprise agents.