@xano/developer-mcp 1.0.26 → 1.0.27

package/dist/xanoscript_docs_auto/tools.md

@@ -1,485 +0,0 @@
----
-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
-}
-```