Tool Parameters

This guide provides detailed information on defining parameters for Cognipeer custom tools. Well-designed parameters ensure your tools are used effectively by AI assistants.

Parameter Schema Basics

Parameters for Cognipeer custom tools use JSON Schema to define their structure, types, and validation rules. Each action in a custom tool includes a parameters object that follows this pattern:

"parameters": {
  "type": "object",
  "properties": {
    "parameterName": {
      "type": "string",
      "description": "Description of what this parameter does",
      "required": true
    },
    // Additional parameters...
  }
}

Supported Parameter Types

String Parameters

For text inputs:

"customerName": {
  "type": "string",
  "description": "The customer's full name",
  "required": true,
  "minLength": 2,
  "maxLength": 100
}

Common string constraints:

• minLength: Minimum number of characters
• maxLength: Maximum number of characters
• pattern: Regular expression pattern to validate input
• format: Predefined formats like "email", "date-time", "uri"
• enum: List of allowed values

Number Parameters

For numeric inputs:

"quantity": {
  "type": "number",
  "description": "Quantity of items to order",
  "required": true,
  "minimum": 1,
  "maximum": 100
}

Common number constraints:

• minimum: Minimum allowed value
• maximum: Maximum allowed value
• multipleOf: Value must be a multiple of this number
• exclusiveMinimum: Value must be greater than (not equal to) this number
• exclusiveMaximum: Value must be less than (not equal to) this number

Boolean Parameters

For true/false options:

"isPriority": {
  "type": "boolean",
  "description": "Whether this is a priority order",
  "required": false,
  "default": false
}

Array Parameters

For lists of values:

"productIds": {
  "type": "array",
  "description": "List of product IDs to include in the order",
  "required": true,
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10
}

Common array constraints:

• minItems: Minimum number of items
• maxItems: Maximum number of items
• uniqueItems: Whether all items must be unique
• items: Schema for the items in the array

Object Parameters

For structured data:

"address": {
  "type": "object",
  "description": "Shipping address",
  "required": true,
  "properties": {
    "street": {
      "type": "string",
      "required": true
    },
    "city": {
      "type": "string",
      "required": true
    },
    "state": {
      "type": "string",
      "required": true
    },
    "zipCode": {
      "type": "string",
      "required": true
    },
    "country": {
      "type": "string",
      "required": true
    }
  }
}

Required vs. Optional Parameters

Mark parameters as required when they're essential:

"customerId": {
  "type": "string",
  "description": "The unique identifier of the customer",
  "required": true
}

For optional parameters, either omit the required property or set it to false:

"notes": {
  "type": "string",
  "description": "Additional notes about the customer",
  "required": false
}

Default Values

Specify default values for optional parameters:

"limit": {
  "type": "number",
  "description": "Maximum number of results to return",
  "required": false,
  "default": 10,
  "maximum": 100
}

Enumerated Values

Restrict a parameter to specific values:

"status": {
  "type": "string",
  "description": "Status of the order",
  "required": true,
  "enum": ["pending", "processing", "shipped", "delivered", "cancelled"]
}

Parameter Descriptions

Write clear, detailed descriptions for each parameter:

"searchTerm": {
  "type": "string",
  "description": "Keywords to search for in product names and descriptions. Multiple keywords should be separated by spaces.",
  "required": true
}

Good descriptions help the AI understand:

• What the parameter is for
• What format the value should be in
• Any constraints or special considerations

Advanced Parameter Features

Conditional Parameters

Some parameters may only be relevant based on other parameters:

"parameters": {
  "type": "object",
  "properties": {
    "filterType": {
      "type": "string",
      "description": "Type of filter to apply",
      "required": true,
      "enum": ["date", "category", "status"]
    },
    "dateFrom": {
      "type": "string",
      "description": "Start date for date filter (format: YYYY-MM-DD)",
      "format": "date"
    },
    "dateTo": {
      "type": "string",
      "description": "End date for date filter (format: YYYY-MM-DD)",
      "format": "date"
    },
    "category": {
      "type": "string",
      "description": "Category name for category filter"
    },
    "status": {
      "type": "string",
      "description": "Status value for status filter",
      "enum": ["active", "inactive", "pending"]
    }
  }
}

In this example, which parameters are needed depends on the selected filterType.

Nested Objects

For complex data structures, use nested objects:

"orderDetails": {
  "type": "object",
  "description": "Details of the order",
  "required": true,
  "properties": {
    "items": {
      "type": "array",
      "description": "Items in the order",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "required": true
          },
          "quantity": {
            "type": "number",
            "required": true,
            "minimum": 1
          },
          "price": {
            "type": "number",
            "required": true,
            "minimum": 0
          }
        }
      }
    },
    "shipping": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "required": true,
          "enum": ["standard", "express", "overnight"]
        },
        "cost": {
          "type": "number",
          "required": true
        }
      }
    }
  }
}

Parameter Handling Tips

Validating User Input

When the AI asks for parameter values from the user, it will:

1. Extract information from the conversation when possible
2. Ask follow-up questions for missing required parameters
3. Validate that inputs meet the constraints in your schema
4. Format the data according to your parameter types

Parameter Extraction

The AI extracts parameters from user queries when possible. For example:

User: "Show me order #12345" AI extracts: { "orderId": "12345" }

User: "Find all shirts in size large and color blue" AI extracts: { "category": "shirts", "size": "large", "color": "blue" }

Parameter Best Practices

1. Be Specific: Use clear, specific parameter names
2. Limit Required Parameters: Only mark parameters as required if absolutely necessary
3. Provide Defaults: Use default values for optional parameters when appropriate
4. Add Constraints: Use validation rules to ensure proper data format
5. Prioritize Usability: Design parameters thinking about how users will provide the information in conversation

Example Parameter Scenarios

Search Parameters

"parameters": {
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term to find products",
      "required": true
    },
    "category": {
      "type": "string",
      "description": "Product category to filter by",
      "required": false
    },
    "minPrice": {
      "type": "number",
      "description": "Minimum price filter",
      "required": false,
      "minimum": 0
    },
    "maxPrice": {
      "type": "number",
      "description": "Maximum price filter",
      "required": false,
      "minimum": 0
    },
    "sort": {
      "type": "string",
      "description": "Sort order for results",
      "required": false,
      "enum": ["price_asc", "price_desc", "newest", "popularity"],
      "default": "popularity"
    }
  }
}

Date Range Parameters

"parameters": {
  "type": "object",
  "properties": {
    "startDate": {
      "type": "string",
      "description": "Start date in YYYY-MM-DD format",
      "required": true,
      "format": "date"
    },
    "endDate": {
      "type": "string",
      "description": "End date in YYYY-MM-DD format",
      "required": true,
      "format": "date"
    },
    "includeWeekends": {
      "type": "boolean",
      "description": "Whether to include weekends in the report",
      "required": false,
      "default": true
    }
  }
}

Testing Your Parameters

To test your parameter definitions:

1. Create a basic tool with your parameter schema
2. Register it in the Cognipeer platform
3. Start a conversation with a Peer that has the tool enabled
4. Ask questions that should trigger the tool
5. Observe how the AI collects and validates the parameters
6. Refine your schema based on the interaction

Next Steps

• Custom Tool Format: Complete reference for the custom tool JSON structure
• Creating Custom Tools: Step-by-step guide to building custom tools
• Examples: Sample implementations of custom tools with various parameter types