api-ai-augmented

AI-Augmented API Skill

Design LLM tool definitions, agentic workflows, and natural language API interfaces.

---

Anthropic Tool Use Definition

{
  "name": "search_products",
  "description": "Search for products by keyword, category, or price range. Use when the user wants to find, browse, or compare products.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query keywords"
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "books", "home"],
        "description": "Optional category filter"
      },
      "min_price": { "type": "number", "description": "Minimum price in USD" },
      "max_price": { "type": "number", "description": "Maximum price in USD" },
      "limit": { "type": "integer", "default": 10, "description": "Max results to return" }
    },
    "required": ["query"]
  }
}

---

OpenAI Function Calling Definition

{
  "type": "function",
  "function": {
    "name": "create_order",
    "description": "Create a new order for a user. Use when the user wants to purchase a product. Always confirm product and quantity before calling.",
    "parameters": {
      "type": "object",
      "properties": {
        "product_id": { "type": "string", "description": "The product ID to order" },
        "quantity": { "type": "integer", "minimum": 1, "description": "Quantity to order" },
        "shipping_address": {
          "type": "object",
          "properties": {
            "street": { "type": "string" },
            "city": { "type": "string" },
            "country": { "type": "string" }
          },
          "required": ["street", "city", "country"]
        }
      },
      "required": ["product_id", "quantity", "shipping_address"]
    }
  }
}

---

MCP (Model Context Protocol) Tool Schema

{
  "name": "get_build_status",
  "description": "Get the status of a HyperExecute test job. Use when the user asks about test results, job status, or CI build outcomes.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "job_id": { "type": "string", "description": "The HyperExecute job ID" }
    },
    "required": ["job_id"]
  }
}

? Real-World Integration — TestMu AI HyperExecute Build MCP tools that let AI agents query and control test jobs via the HyperExecute API. Docs: https://www.testmuai.com/support/api-doc/?key=hyperexecute

---

Tool Design Principles

1. One tool = one action: Don't combine search + filter + sort into one tool. Split them.
2. Description drives routing: The LLM picks tools from descriptions — be specific and include trigger phrases.
3. Required vs optional: Only mark fields required if the API truly needs them.
4. Enum for constrained values: Use enum instead of string for fixed-choice fields.
5. Idempotent where possible: Prefer read tools over write tools for exploration.
6. Confirm before destructive actions: Description should say "Always confirm with the user before calling."

---

Agentic Workflow Example

User: "Get me the status of my last 3 test builds"

Agent plan:
  1. call list_jobs(limit=3, sort="created_at:desc")
     → returns [{id: "job_1", status: "passed"}, {id: "job_2", status: "failed"}, ...]
  2. call get_job_details(job_id="job_2")  // dig into the failed one
     → returns task breakdown, error logs
  3. Synthesize: "Your last 3 builds: job_1 passed, job_2 failed (2 of 15 tasks failed on Chrome/Win10), job_3 passed."

---

Natural Language → API Mapping Table

Build this mapping for any domain:

Natural language intent	API call
"Find hotels in Paris"	GET /hotels/search?location=Paris
"Book a room for 2 nights"	POST /bookings
"Cancel my reservation"	POST /bookings/{id}/cancel
"Show my past orders"	GET /orders?user=me&sort=date:desc
"Is the API working?"	GET /health/ready

---

API-as-Plugin (OpenAPI → GPT Plugin / Tool)

Minimal ai-plugin.json:

{
  "schema_version": "v1",
  "name_for_human": "My API",
  "name_for_model": "my_api",
  "description_for_human": "Access my service's data and actions.",
  "description_for_model": "Use this plugin to search, create, update and delete resources in My API. Always prefer specific endpoints over generic ones. Confirm destructive actions with the user first.",
  "auth": { "type": "oauth" },
  "api": { "type": "openapi", "url": "https://api.example.com/openapi.json" }
}