API AI Augmented

# AI-Augmented API Skill

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

---

## Anthropic Tool Use Definition

```json
{
  "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

```json
{
  "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

```json
{
  "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`:
```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" }
}
```