@xano/developer-mcp 1.0.21 → 1.0.22

package/dist/xanoscript_docs_auto/tools.md

@@ -0,0 +1,485 @@
+---
+applyTo: "tools/**/*.xs"
+---
+
+# AI Tools
+
+Tool definitions for AI agents and MCP servers.
+
+## Quick Reference
+
+```xs
+tool "<name>" {
+  description = "What this tool does"
+  input {
+    text parameter_name description="Parameter description"
+  }
+  stack {
+    // Tool implementation
+  }
+  response = $result
+}
+```
+
+---
+
+## Tool Definition
+
+### Basic Tool
+
+```xs
+tool "get_weather" {
+  description = "Get current weather for a location"
+  input {
+    text city description="City name"
+    text? country description="Country code (optional)"
+  }
+  stack {
+    api.request {
+      url = "https://api.weather.com/current"
+      params = {
+        city: $input.city,
+        country: $input.country ?? "US"
+      }
+      headers = {
+        "Authorization": "Bearer " ~ $env.WEATHER_API_KEY
+      }
+    } as $weather
+  }
+  response = {
+    city: $input.city,
+    temperature: $weather.temp,
+    conditions: $weather.conditions
+  }
+}
+```
+
+### Database Query Tool
+
+```xs
+tool "search_products" {
+  description = "Search for products by name or category"
+  input {
+    text? query description="Search query"
+    text? category description="Product category"
+    int? limit description="Maximum results" default=10
+  }
+  stack {
+    db.query product {
+      where = $db.product.active == true
+            && $db.product.name ilike? ("%" ~ $input.query ~ "%")
+            && $db.product.category ==? $input.category
+      order_by = {field: "name", direction: "asc"}
+      return = {type: "list", paging: {per_page: $input.limit}}
+    } as $products
+  }
+  response = $products|map:{
+    id: $$.id,
+    name: $$.name,
+    price: $$.price,
+    stock: $$.stock
+  }
+}
+```
+
+---
+
+## Tool Input Parameters
+
+### Required Parameters
+
+```xs
+input {
+  text name description="User's full name"
+  email email description="User's email address"
+  int quantity description="Number of items"
+}
+```
+
+### Optional Parameters
+
+```xs
+input {
+  text query description="Search query"
+  text? category description="Filter by category"
+  int? limit description="Max results" default=20
+  text? sort description="Sort field" default="created_at"
+}
+```
+
+### Complex Types
+
+```xs
+input {
+  json filters description="Filter criteria object"
+  array<text> tags description="Tags to filter by"
+  object options description="Additional options"
+}
+```
+
+---
+
+## Tool Responses
+
+### Simple Response
+
+```xs
+response = $result
+```
+
+### Structured Response
+
+```xs
+response = {
+  success: true,
+  data: $result,
+  count: $result|count
+}
+```
+
+### Mapped Response
+
+```xs
+response = $items|map:{
+  id: $$.id,
+  name: $$.name,
+  summary: $$.description|substr:0:100
+}
+```
+
+---
+
+## Common Tool Patterns
+
+### Lookup Tool
+
+```xs
+tool "get_order" {
+  description = "Get order details by order number"
+  input {
+    text order_number description="The order number to look up"
+  }
+  stack {
+    db.get order {
+      field_name = "order_number"
+      field_value = $input.order_number
+      addons = [order_items, shipping_address]
+    } as $order
+
+    conditional {
+      if ($order == null) {
+        return {
+          value = {error: "Order not found"}
+        }
+      }
+    }
+  }
+  response = {
+    order_number: $order.order_number,
+    status: $order.status,
+    total: $order.total,
+    items: $order.order_items,
+    shipping: $order.shipping_address
+  }
+}
+```
+
+### Search Tool
+
+```xs
+tool "search_knowledge_base" {
+  description = "Search the knowledge base for articles"
+  input {
+    text query description="Search query"
+    int? limit description="Maximum results" default=5
+  }
+  stack {
+    db.query article {
+      where = $db.article.published == true
+            && ($db.article.title ilike ("%" ~ $input.query ~ "%")
+                || $db.article.content search $input.query)
+      order_by = {field: "relevance", direction: "desc"}
+      return = {type: "list", paging: {per_page: $input.limit}}
+    } as $articles
+  }
+  response = $articles|map:{
+    title: $$.title,
+    summary: $$.content|substr:0:200,
+    url: "/articles/" ~ $$.slug
+  }
+}
+```
+
+### Action Tool
+
+```xs
+tool "create_ticket" {
+  description = "Create a support ticket"
+  input {
+    text subject description="Ticket subject"
+    text description description="Detailed description"
+    text? priority description="Priority level" default="normal"
+  }
+  stack {
+    db.add ticket {
+      data = {
+        subject: $input.subject,
+        description: $input.description,
+        priority: $input.priority,
+        status: "open",
+        created_at: now
+      }
+    } as $ticket
+  }
+  response = {
+    ticket_id: $ticket.id,
+    message: "Ticket created successfully"
+  }
+}
+```
+
+### Calculation Tool
+
+```xs
+tool "calculate_shipping" {
+  description = "Calculate shipping cost for an order"
+  input {
+    decimal weight description="Total weight in kg"
+    text destination description="Destination country code"
+    text? method description="Shipping method" default="standard"
+  }
+  stack {
+    // Get shipping rates
+    db.get shipping_rate {
+      field_name = "country_code"
+      field_value = $input.destination
+    } as $rate
+
+    var $base_cost { value = $rate.base_cost }
+    var $per_kg { value = $rate.per_kg }
+
+    var $shipping_cost {
+      value = $base_cost + ($input.weight * $per_kg)
+    }
+
+    conditional {
+      if ($input.method == "express") {
+        var.update $shipping_cost {
+          value = $shipping_cost * 1.5
+        }
+      }
+    }
+  }
+  response = {
+    cost: $shipping_cost|round:2,
+    currency: "USD",
+    method: $input.method,
+    estimated_days: $input.method == "express" ? 3 : 7
+  }
+}
+```
+
+### External API Tool
+
+```xs
+tool "get_exchange_rate" {
+  description = "Get current exchange rate between currencies"
+  input {
+    text from description="Source currency code (e.g., USD)"
+    text to description="Target currency code (e.g., EUR)"
+  }
+  stack {
+    api.request {
+      url = "https://api.exchangerate.com/latest"
+      params = {
+        base: $input.from
+      }
+      headers = {
+        "Authorization": "Bearer " ~ $env.EXCHANGE_API_KEY
+      }
+    } as $rates
+  }
+  response = {
+    from: $input.from,
+    to: $input.to,
+    rate: $rates.rates|get:$input.to,
+    timestamp: now|format_timestamp:"Y-m-d H:i:s":"UTC"
+  }
+}
+```
+
+---
+
+## Tool Calling
+
+### From Agent
+
+Tools are automatically called by agents when needed. The agent decides when to use a tool based on its description and the user's request.
+
+### Direct Call
+
+```xs
+tool.call {
+  name = "search_products"
+  input = {
+    query: "laptop",
+    limit: 5
+  }
+} as $products
+```
+
+---
+
+## Error Handling
+
+```xs
+tool "risky_operation" {
+  description = "Perform an operation that might fail"
+  input {
+    text data description="Data to process"
+  }
+  stack {
+    try_catch {
+      try {
+        function.run "process_data" {
+          input = {data: $input.data}
+        } as $result
+      }
+      catch {
+        return {
+          value = {
+            success: false,
+            error: $error.message
+          }
+        }
+      }
+    }
+  }
+  response = {
+    success: true,
+    result: $result
+  }
+}
+```
+
+---
+
+## Tool Documentation
+
+Well-documented tools help AI agents use them correctly:
+
+```xs
+tool "update_inventory" {
+  description = """
+Update product inventory levels.
+
+Use this tool when:
+- A sale is made (decrease stock)
+- Inventory is restocked (increase stock)
+- Stock needs adjustment
+
+Returns the updated inventory count.
+"""
+  input {
+    int product_id description="The ID of the product to update"
+    int adjustment description="Amount to adjust (positive to add, negative to subtract)"
+    text? reason description="Reason for adjustment (optional but recommended)"
+  }
+  stack {
+    db.patch product {
+      field_name = "id"
+      field_value = $input.product_id
+      data = {
+        stock: $db.product.stock + $input.adjustment,
+        updated_at: now
+      }
+    } as $product
+
+    // Log the adjustment
+    db.add inventory_log {
+      data = {
+        product_id: $input.product_id,
+        adjustment: $input.adjustment,
+        reason: $input.reason,
+        new_stock: $product.stock,
+        created_at: now
+      }
+    }
+  }
+  response = {
+    product_id: $product.id,
+    new_stock: $product.stock,
+    adjustment_logged: true
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### Clear Descriptions
+
+```xs
+// Good: Specific and actionable
+description = "Search for products by name, category, or price range. Returns up to 20 matching products with name, price, and availability."
+
+// Bad: Vague
+description = "Search products"
+```
+
+### Parameter Documentation
+
+```xs
+input {
+  text query description="Full or partial product name to search for"
+  decimal? min_price description="Minimum price filter in USD"
+  decimal? max_price description="Maximum price filter in USD"
+  bool? in_stock_only description="If true, only return products with stock > 0" default=false
+}
+```
+
+### Return Useful Data
+
+```xs
+// Return data the agent can work with
+response = {
+  found: $results|count,
+  products: $results|map:{
+    id: $$.id,
+    name: $$.name,
+    price: $$.price,
+    available: $$.stock > 0
+  },
+  has_more: $total > $limit
+}
+```
+
+### Handle Edge Cases
+
+```xs
+tool "get_user_profile" {
+  input {
+    int user_id
+  }
+  stack {
+    db.get user {
+      field_name = "id"
+      field_value = $input.user_id
+    } as $user
+
+    // Handle not found
+    conditional {
+      if ($user == null) {
+        return {
+          value = {
+            error: "User not found",
+            user_id: $input.user_id
+          }
+        }
+      }
+    }
+  }
+  response = $user
+}
+```