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

Type	Example value	Notes
`string`	`"shoe-01"`	Most common
`number`	`2`	Integers and floats
`boolean`	`true`
`array`	`["a", "b"]`	Specify `items` type
`object`	`{ "key": "val" }`	Nested parameters

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