Input Schema Format

The input schema defines the parameters your tool accepts. It follows JSON Schema draft 7.

Basic structure

{
  "type": "object",
  "properties": {
    "paramName": {
      "type": "string",
      "description": "What this parameter is for"
    }
  },
  "required": ["paramName"]
}

Supported types

The description field

Write descriptions for AI agents, not humans. The agent reads these to understand what to pass.

// Bad
"description": "Product ID"
 
// Good
"description": "The product SKU from the URL path, e.g. shoe-01 or jacket-blue-xl"

Required vs optional

Fields listed in required must be provided by the agent. Optional fields may be omitted.

{
  "type": "object",
  "properties": {
    "productId": { "type": "string", "description": "Required product ID" },
    "quantity":  { "type": "number", "description": "Optional quantity, defaults to 1" }
  },
  "required": ["productId"]
}

Array parameters

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of tag names to apply"
    }
  }
}

No-parameter tools

A tool that takes no input still needs a valid schema:

{ "type": "object", "properties": {} }

Common mistakes

• Missing "type": "object" at the top level — the schema must be an object type
• Using integer instead of number — use number for all numeric values
• Vague descriptions — the agent may guess wrong values
• Forgetting required — optional fields can be omitted; your executeJs should handle missing values