Tool Parameters

Tool parameters define what inputs your tool accepts. They're specified using JSON Schema format.

Basic Structure

{
  "tool": {
    "name": "tool_name",
    "description": "What the tool does",
    "parameters": {
      "type": "object",
      "properties": {
        "param1": { ... },
        "param2": { ... }
      },
      "required": ["param1"]
    }
  }
}

Parameter Types

String

{
  "city": {
    "type": "string",
    "description": "City name (e.g., 'London', 'Tokyo')"
  }
}

Number

{
  "temperature": {
    "type": "number",
    "description": "Temperature in Celsius"
  }
}

Integer

{
  "count": {
    "type": "integer",
    "description": "Number of items to return"
  }
}

Boolean

{
  "includeDetails": {
    "type": "boolean",
    "description": "Whether to include detailed information"
  }
}

Array

{
  "tags": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "description": "List of tags to filter by"
  }
}

Object

{
  "filters": {
    "type": "object",
    "properties": {
      "minPrice": { "type": "number" },
      "maxPrice": { "type": "number" }
    },
    "description": "Filter criteria"
  }
}

Enums

Restrict values to a predefined set:

{
  "action": {
    "type": "string",
    "enum": ["search", "read", "send", "delete"],
    "description": "The action to perform"
  }
}

The AI will only use these exact values.

Required Parameters

List parameters that must be provided:

{
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query" },
      "maxResults": { "type": "integer", "description": "Max results" }
    },
    "required": ["query"]
  }
}

query is required, maxResults is optional.

Descriptions

Write clear descriptions. The AI uses these to understand when and how to use each parameter.

Good:

{
  "query": {
    "type": "string",
    "description": "Gmail search query using Gmail's search syntax (e.g., 'from:[email protected] subject:meeting newer_than:7d')"
  }
}

Bad:

{
  "query": {
    "type": "string",
    "description": "Search query"
  }
}

Defaults in Code

Handle optional parameters with defaults in your code:

async function handler(input, context) {
  const { 
    query,
    maxResults = 10,  // Default value
    includeArchived = false 
  } = input;
  
  // ...
}

Complex Example

{
  "tool": {
    "name": "search_products",
    "description": "Search for products in the catalog",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search text to match product names and descriptions"
        },
        "category": {
          "type": "string",
          "enum": ["electronics", "clothing", "home", "sports"],
          "description": "Product category to filter by"
        },
        "priceRange": {
          "type": "object",
          "properties": {
            "min": {
              "type": "number",
              "description": "Minimum price in USD"
            },
            "max": {
              "type": "number", 
              "description": "Maximum price in USD"
            }
          },
          "description": "Price range filter"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Product tags to filter by"
        },
        "sortBy": {
          "type": "string",
          "enum": ["price_asc", "price_desc", "newest", "popular"],
          "description": "How to sort results"
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of results (default: 20)"
        }
      },
      "required": ["query"]
    }
  }
}

Tips

1. Required first - List commonly-used required params first
2. Sensible defaults - Make optional params work well with defaults
3. Clear enums - Use descriptive enum values
4. Complete descriptions - Include examples and valid values
5. Flat when possible - Nested objects are harder for the AI to fill

How the AI Uses Parameters

When the AI decides to call your tool:

1. It reads the tool's description
2. It reads each parameter's description
3. It constructs the input object
4. PIE validates against your schema
5. Your handler receives the input object

// User: "What's the weather in Tokyo?"
// AI constructs: { city: "Tokyo" }

async function handler(input, context) {
  const { city } = input;  // "Tokyo"
  // ...
}