Designing Agent-Compatible APIs: A Spec for the Future

As agentic AI adoption grows in logistics, a new reality is becoming clear: many APIs need to be reimagined for use by autonomous agents, not just humans or scripts.

This article proposes a practical design spec for agent-compatible APIs, drawing from current LLM limitations, developer feedback, and real-world logistics use cases.

Whether you’re building new APIs or retrofitting legacy systems, these best practices will help make your tools understandable and usable by AI agents.

What Makes an API Agent-Compatible?

Agentic AI tools rely on LLMs to:

• Interpret goals in natural language

• Choose the correct API or tool

• Generate valid parameters

• Interpret and reason over results

But most APIs today are:

• Designed for humans with domain expertise

• Inconsistently documented

• Structured for machine efficiency, not interpretability

To bridge this gap, agent-usable APIs must become declarative, descriptive, and constrained.

Agentic API Design Principles

1. Flat Parameter Structures

Avoid deeply nested or ambiguous JSON schemas.

✅ Do this:

{

  "origin_zip": "90210",

  "destination_zip": "10001",

  "weight_lbs": 120,

  "service_level": "standard"

}

❌ Not this:

{

  "shipment": {

    "route": {

      "from": { "postal": "90210" },

      "to": { "postal": "10001" }

    }

  }

}

2. Descriptive Metadata (Using JSON Schema or OpenAPI)

Every parameter should include:

• A description

• Expected types (string, number, enum)

• Example values

• Required/optional flags

This allows agents to auto-complete inputs more reliably.

3. Enum Constraints and Value Hints

Avoid free-text parameters where possible. Define enums and common values explicitly.

✅ Good:

"service_level": {

  "type": "string",

  "enum": ["standard", "expedited", "overnight"]

}

❌ Risky:

"service_level": "any string"

4. Clear Error Handling

Return structured, actionable errors. Include:

• Field-specific validation messages

• Suggested corrections or enum values

• Status codes + reasons

This helps the agent retry intelligently.

5. Consistent Naming Across Endpoints

Standardize field names and formats:

• Always use origin_zip, never origZip, zipFrom, etc.

• Stick to a unit convention (lbs, inches, USD)

• Use snake_case or camelCase consistently

6. Read-Only Mode (for Validation)

Support a dry-run or validation flag that:

• Accepts input

• Performs all validation

• Returns a report but takes no action

This lets agents safely experiment with tool usage.

7. Descriptions for the Entire Tool (Not Just Fields)

Provide a plain-language description of what the API/tool does.

• "This endpoint creates an LTL shipment with basic freight details."

• "Use this to get a quote based on ZIP codes and weight."

LLMs use this to select the right tool in a multi-tool environment.

Example: Agent-Friendly API Spec

Here's a simplified shipping quote endpoint designed for agent use:

{

  "name": "get_quote",

  "description": "Retrieves an LTL rate quote based on shipment details.",

  "parameters": {

    "origin_zip": {

      "type": "string",

      "description": "Origin ZIP code",

      "example": "90210"

    },

    "destination_zip": {

      "type": "string",

      "description": "Destination ZIP code",

      "example": "10001"

    },

    "weight_lbs": {

      "type": "number",

      "description": "Total shipment weight in pounds",

      "example": 150

    },

    "service_level": {

      "type": "string",

      "enum": ["standard", "expedited"],

      "description": "Desired service level"

    }

  }

}

Where Splice Fits

Our platform already helps logistics teams build and expose APIs through:

• Event-driven workflows

• Tool wrappers with clean inputs

• Normalized naming and data formats

As agentic AI continues to evolve, we’ll support agent-ready tooling and documentation features for our customers.

Summing It Up

Designing agent-usable APIs doesn’t require a complete rewrite of your system. It requires:

• Better documentation and parameter clarity

• Consistent naming and data modeling

• Wrappers that simplify legacy tools

These changes improve automation today and future-proof your infrastructure for LLM-powered agents tomorrow.

Want Help Making Your APIs Agent-Friendly?

• Talk to our team.

• Try our automation platform for logistics.

• Subscribe or follow us to keep learning about APIs