Writing tool schemas for Python tools

Define schemas for watsonX Orchestrate Python tools. A tool schema defines the structure of data that flows into and out of your Python tools. It consists of two parts:

input_schema: Defines what parameters a tool accepts. Wrap it in ToolRequestBody.model_validate()
output_schema: Defines what data a tool returns. Wrap it in ToolResponseBody.model_validate()

Import tool, ToolRequestBody, and ToolResponseBody from the ADK package:

Python

from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolRequestBody, ToolResponseBody

Schemas serve multiple purposes:

Runtime validation: Ensures data conforms to expected types and constraints
UI generation: Automatically creates forms in the WatsonX Orchestrate interface
Documentation: Provides clear parameter descriptions for you and LLMs
API integration: Uses in REST APIs for programmatic tool management

Configuring input schemas

Input schemas define the parameters your tool accepts, serving as the contract between your tool and its callers. They specify what data you require, what is optional, and the expected format for each parameter. Input schemas provide validation, automatic UI form generation, clear documentation, type safety, and guidance for AI agents on proper tool usage. Define schemas with clear parameter descriptions, appropriate types, minimal required fields, numeric constraints where applicable, and focused functionality. You can configure input schemas in two primary forms: single required parameter for simple tools, or multiple parameters with a mix of required and optional fields for more complex operations.

Configuring single parameter

This form of input schema has one required parameter. Use this pattern when your tool needs exactly one piece of information to function.

Python

@tool(
    description="Retrieves allowed values for the Country field",
    input_schema=ToolRequestBody.model_validate({
        "type": "object",
        "properties": {
            "substring": {
                "type": "string",
                "description": "Case-insensitive substring to filter countries. For example, use 'United' or 'Canada'",
            },
        },
        "required": ["substring"],
        "additionalProperties": False,
    }),
)
def search_countries(substring: str) -> str:
    # Implementation
    pass

Configuring multiple parameters

When your tool needs multiple pieces of information, define a mix of required and optional parameters. This pattern is common for update operations where you must provide some fields while others remain optional.

Required parameters: List them in the required array
Optional parameters: Do not include them in the required array. Use | None (Python 3.10+) or Optional[T] from typing in the function signature
Default values: Give optional parameters = None as default value

Python

@tool(
    description="Updates an existing payment method",
    input_schema=ToolRequestBody.model_validate({
        "type": "object",
        "properties": {
            "payment_method_id": {
                "type": "string",
                "description": "The unique identifier of the payment method to update",
            },
            "nickname": {
                "type": "string",
                "description": "Optional new nickname for the payment method",
            },
            "expiry_month": {
                "type": "integer",
                "minimum": 1,
                "maximum": 12,
                "description": "Optional new expiry month (1-12)",
            },
            "is_default": {
                "type": "boolean",
                "description": "Optional flag to set this as the default payment method",
            },
        },
        "required": ["payment_method_id"],
        "additionalProperties": False,
    }),
)
def update_payment_method(
    payment_method_id: str,
    nickname: str | None = None,
    expiry_month: int | None = None,
    is_default: bool | None = None,
) -> str:
    # Implementation
    pass

Configuring output schemas

Output schemas define the structure of data your tool returns, serving as the contract between your tool and its consumers. They specify the format and type of data that callers can expect to receive. Output schemas provide validation, automatic UI display generation, clear documentation, type safety, and proper data flow between tools and agents. Define schemas with clear descriptions, appropriate types, and structures that match your return values exactly. You can configure output schemas in two primary forms: simple string returns for unstructured or formatted text, or Pydantic models for structured data with multiple fields.

Returning simple parameters

Use simple string returns for tools that return unstructured text or single values. This is the most common pattern for tools that format their output as human-readable text.

Python

output_schema=ToolResponseBody.model_validate({
    "type": "string",
    "description": "A human-readable string containing the result data",
})

Function signature:

Python

def tool_name(...) -> str:
    return str(data)

Returning multiple parameters

When your tool returns structured data with multiple fields of different types, use Pydantic models as return types. For more information, see Pydantic models.

Configuring dynamic schemas

In integration-heavy environments, schemas change frequently. Dynamic input and output schemas enable select fields in a tool’s input to be mutable at runtime—securely and predictably—without affecting immutable core fields. Use dynamic schemas when:

You need to add new attributes to objects such as CRM records
You need a small number of user-defined fields beyond a stable core API
You want Builder UI users to change types for dynamic fields only. For example, change string to number

Python

from ibm_watsonx_orchestrate.agent_builder.tools import tool


@tool(
    enable_dynamic_input_schema=True,   # must be True for dynamic_input_schema to take effect
    enable_dynamic_output_schema=True,  # must be True for dynamic_output_schema to take effect
    dynamic_input_schema={  # schema for the extra **kwargs fields
        'type': 'object',
        'properties': {
            'c': {'type': 'integer', 'description': 'The third integer to add'}
        },
        'required': []
    },
    dynamic_output_schema={  # schema for the extra fields in the returned dict
        'type': 'object',
        'properties': {
            'sum': {'type': 'integer', 'description': 'The sum of a, b and c'},
            'c': {'type': 'integer', 'description': 'The third integer to add'}
        },
        'required': []
    }
)
def add_kwargs(a: int, b: int, **kwargs) -> dict:
    """
    Adds a, b, and an optional c (from kwargs) and returns the result.

    Args:
        a (int): The first integer to add.
        b (int): The second integer to add.

    Returns:
        dict: A dictionary with keys 'sum' (total of a + b + c) and 'c' (value of c, defaulting to 0).

    Example:
        >>> add_kwargs(3, 5, c=2)
        {'sum': 10, 'c': 2}
    """
    sum = a + b + kwargs.get("c", 0)
    return {'sum': sum, 'c': kwargs.get("c", 0)}


if __name__ == "__main__":
    print(add_kwargs(1, 2, c=3))

Python

from ibm_watsonx_orchestrate.agent_builder.tools import tool


@tool(
    enable_dynamic_input_schema=True,   # must be True for dynamic_input_schema to take effect
    enable_dynamic_output_schema=True,  # must be True for dynamic_output_schema to take effect
    dynamic_input_schema={  # schema for the extra **kwargs fields
        'type': 'object',
        'properties': {
            'c': {'type': 'string', 'description': 'The third word'}
        },
        'required': []
    },
    dynamic_output_schema={  # schema for the extra fields in the returned dict
        'type': 'object',
        'properties': {
            'message': {'type': 'string', 'description': 'The message that combines a, b and c'},
            'c': {'type': 'string', 'description': 'The third word'}
        },
        'required': []
    }
)
def combine_words(a: str, b: str, **kwargs) -> dict:
    """
    Receive required three inputs as a, b, c.
    Combine them and returns the result.

    Args:
        a (string): The first word.
        b (string): The second word.


    Returns:
        message: The message combines `a` and `b`.

    Example:
        >>> combine_words("hello", "world")
        "helloworld"
    """
    message = a + b + kwargs.get("c", "")
    return {'message': message, 'c': kwargs.get("c", "")}


if __name__ == "__main__":
    print(combine_words("hello", "world", c="Hana"))

Parameter types

JSON Schema supports various data types for defining tool parameters. Each type has specific properties and validation rules that help ensure data integrity and provide clear documentation.

String

Use the string type for text-based parameters such as names, descriptions, identifiers, or any free-form text input.

Python

"parameter_name": {
    "type": "string",
    "description": "Description of the parameter",
}

Integer

Use the integer type for whole numbers without decimal points. This is ideal for counts, indices, IDs, or any numeric value that should not have fractional parts.

Python

"parameter_name": {
    "type": "integer",
    "description": "Description of the parameter",
}

You can add validation constraints to ensure values fall within acceptable ranges:

Python

"parameter_name": {
    "type": "integer",
    "minimum": 1,
    "maximum": 12,
    "description": "Month value between 1 and 12",
}

Number (Float)

Use the number type for numeric values that may include decimal points. This type accepts both integers and floating-point numbers.

Python

"parameter_name": {
    "type": "number",
    "description": "Description of the parameter",
}

You can add validation constraints to ensure values fall within acceptable ranges:

Python

"parameter_name": {
    "type": "number",
    "minimum": 1,
    "maximum": 12,
    "description": "Month value between 1 and 12",
}

Boolean

Use the boolean type for true or false values.

Python

"parameter_name": {
    "type": "boolean",
    "description": "Description of the parameter",
}

Date

Use the string type with format: "date" for date values. Dates must be in ISO 8601 format: YYYY-MM-DD.

Python

"parameter_name": {
    "type": "string",
    "format": "date",
    "description": "Date in YYYY-MM-DD format",
}

Example values: "2024-01-15", "2023-12-31", "2025-06-01"

Nested object

Use the object type for complex parameters that contain multiple related fields. This allows you to group related data together in a structured way.

Python

"parameter_name": {
    "type": "object",
    "description": "Description of the object",
    "properties": {
        "nested_field1": {
            "type": "string",
            "description": "Description of nested field",
        },
        "nested_field2": {
            "type": "string",
            "description": "Description of nested field",
        },
    },
    "required": ["nested_field1", "nested_field2"],
}

Best practices:

Always include a description for the object and each nested field
Use the required array to specify which nested fields are mandatory
Keep nesting levels reasonable and avoid deeply nested structures when possible
Consider using Pydantic models for complex nested structures. For more information, see Pydantic models

Pydantic models

When you have complex nested structures or want type-safe parameter definitions, you can define Pydantic models and use them as both input parameters and return types. Benefits of Pydantic models:

Type validation: Automatic validation of data structure
Clear contracts: Explicit definition of what the tool accepts and returns
IDE support: Autocomplete and type hints when working with parameters and results
Reusability: Use models across multiple tools
Documentation: Self-documenting parameters and return values

Using as input parameters

First, create your Pydantic model classes with clear docstrings and type hints:

Python

from pydantic import BaseModel

class ReadDocumentPageRange(BaseModel):
    """Inclusive, 1-indexed range of pages to read from a document."""
    start: int
    end: int

class NamedDocument(BaseModel):
    """A reference to a previously uploaded document."""
    name: str
    key: str

Then, use your Pydantic models in the input schema. Each field in the model must be represented in the schema properties:

Python

@tool(
    description="Reads content from a document with optional page range",
    input_schema=ToolRequestBody.model_validate({
        "type": "object",
        "properties": {
            "key": {
                "type": "string",
                "description": "The unique key associated with the document",
            },
            "page_range": {
                "type": "object",
                "description": "Optional range of pages to read",
                "properties": {
                    "start": {
                        "type": "integer",
                        "description": "The 1-indexed page number to start reading at",
                    },
                    "end": {
                        "type": "integer",
                        "description": "The page number to end reading at (inclusive)",
                    },
                },
                "required": ["start", "end"],
            },
        },
        "required": ["key"],
        "additionalProperties": False,
    }),
)
def read_document(
    key: str,
    page_range: ReadDocumentPageRange | None = None
) -> str:
    """Reads content from a document with optional page range filtering.
    
    Args:
        key: Unique identifier for the document
        page_range: Optional page range to read. If None, reads entire document
    
    Returns:
        Document content as a string
    """
    # Implementation
    pass

Important:

Use descriptive class names that clearly indicate the data structure
Add docstrings to explain what the model represents
Define all fields with appropriate type hints
Use optional fields with | None or Optional[T] for non-required parameters
Match the schema properties to the Pydantic model fields exactly
Include required fields in the model in the schema’s required array
Ensure each nested object in the schema corresponds to a Pydantic model

Using as return parameter

When your tool returns structured data with multiple fields of different types, define a Pydantic model as the return type. This provides type safety and clear structure for complex return values. Define the Pydantic model:

Python

from pydantic import BaseModel

class DocumentUploadResult(BaseModel):
    """Result returned after uploading a document."""
    status: str
    key: str

Use in output schema: Match the output schema exactly to your Pydantic model’s structure:

Python

@tool(
    description="Accepts a document upload from the user",
    output_schema=ToolResponseBody.model_validate({
        "type": "object",
        "properties": {
            "status": {
                "type": "string",
                "description": "Status of the upload",
            },
            "key": {
                "type": "string",
                "description": "Unique key identifying the uploaded document",
            },
        },
        "required": ["status", "key"],
        "additionalProperties": False,
    }),
)
def accept_document_upload(content: bytes) -> DocumentUploadResult:
    """Accepts and processes a document upload.
    
    Args:
        content: Raw bytes of the document to upload
    
    Returns:
        DocumentUploadResult with status and unique key
    """
    # Implementation
    pass

Complete example with complex return types: This example shows a tool that returns a complex structure with arrays and nested objects:

Python

from pydantic import BaseModel

class AccountList(BaseModel):
    """List of bank accounts with their details."""
    accounts: list[dict[str, str]]
    total_accounts: int

@tool(
    description="Get a list of all bank accounts with their types and balances",
    output_schema=ToolResponseBody.model_validate({
        "type": "object",
        "properties": {
            "accounts": {
                "type": "array",
                "description": "List of account objects",
                "items": {
                    "type": "object",
                    "properties": {
                        "account_number": {"type": "string"},
                        "account_type": {"type": "string"},
                        "balance": {"type": "number"},
                    },
                },
            },
            "total_accounts": {
                "type": "integer",
                "description": "Total number of accounts",
            },
        },
        "required": ["accounts", "total_accounts"],
        "additionalProperties": False,
    }),
)
def list_accounts() -> AccountList:
    """Retrieves all bank accounts with their details.
    
    Returns:
        AccountList containing all accounts and total count
    """
    # Implementation
    pass

AgentRun context

When your tools need access to user identity, credentials, or context variables, use the AgentRun parameter. This parameter is special and you should NOT include it in the input schema.

The framework automatically injects the AgentRun context parameter. Do not define it in your input schema. Only include it in your function signature.

Python

from ibm_watsonx_orchestrate.run.context import AgentRun

@tool(
    description="Creates a legal matter using user context",
    input_schema=ToolRequestBody.model_validate({
        "type": "object",
        "properties": {
            "matter_title": {
                "type": "string",
                "description": "Title of the legal matter",
            },
            "matter_description": {
                "type": "string",
                "description": "Brief description of the matter",
            },
        },
        "required": ["matter_title", "matter_description"],
        "additionalProperties": False,
    }),
)
def create_matter(context: AgentRun, matter_title: str, matter_description: str) -> str:
    """Creates a new legal matter with user context."""
    # Access user identity from context
    user_email = context.request_context.get('wxo_email_id')
    user_name = context.request_context.get('wxo_user_name')
    
    return f"Matter '{matter_title}' created by {user_name} ({user_email})"

Important rules

Every parameter must have a description - You need this for the parameter to show up in the WatsonX UI
Parameter names must match - Match schema property names exactly to function parameter names
List only required parameters - Only include parameters in the required array that you truly require
Optional parameters - Mark optional parameters with | None (Python 3.10+) or Optional[T] from typing in the function signature, and set their default value to = None
Output schema must match return type - Match the output schema exactly to the Pydantic model structure or return type
Context parameter is special - The framework injects the context: AgentRun parameter and you should NOT include it in the input schema. For more information, see AgentRun context

Function signature must match schema - Match the function parameters to the input schema properties exactly:

Python

input_schema=ToolRequestBody.model_validate({
    "type": "object",
    "properties": {
        "origin": {"type": "string", "description": "..."},
        "destination": {"type": "string", "description": "..."},
        "max_price": {"type": "number", "description": "..."},
    },
    "required": ["origin"],
    "additionalProperties": False,
})

def search_flights(
    origin: str,                    # Required, in "required" list
    destination: str | None = None, # Optional, not in "required" list
    max_price: float | None = None, # Optional, not in "required" list
) -> str:
    # Implementation
    pass

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Configuring input schemas

Configuring single parameter

Configuring multiple parameters

Configuring output schemas

Returning simple parameters

Returning multiple parameters

Configuring dynamic schemas

Parameter types

String

Integer

Number (Float)

Boolean

Date

Nested object

Pydantic models

Using as input parameters

Using as return parameter

AgentRun context

Important rules

See also

​Configuring input schemas

​Configuring single parameter

​Configuring multiple parameters

​Configuring output schemas

​Returning simple parameters

​Returning multiple parameters

​Configuring dynamic schemas

​Parameter types

​String

​Integer

​Number (Float)

​Boolean

​Date

​Nested object

​Pydantic models

​Using as input parameters

​Using as return parameter

​AgentRun context

​Important rules

​See also

Configuring input schemas

Configuring single parameter

Configuring multiple parameters

Configuring output schemas

Returning simple parameters

Returning multiple parameters

Configuring dynamic schemas

Parameter types

String

Integer

Number (Float)

Boolean

Date

Nested object

Pydantic models

Using as input parameters

Using as return parameter

AgentRun context

Important rules

See also