ToolSpec

Class

class ToolSpec:
    name: str
    description: str
    parameters: dict
    returns: dict

Overview

ToolSpec describes a tool’s interface as JSON Schema. It is used by SyntheticWorld to tell the backend what kind of response to generate. In most cases you don’t create ToolSpec manually — the @world.tool decorator calls ToolSpec.from_function() automatically. Use ToolSpec directly when you need full control over the schema.

Constructor

ToolSpec(
    name: str,
    description: str,
    parameters: dict,
    returns: dict,
    param_names: list[str] | None = None,
)

string

required

Tool name. Used as the identifier in world.call().

string

required

Human-readable description of what the tool does.

dict

required

JSON Schema for the tool’s input parameters.

dict

required

JSON Schema for the tool’s return value.

list[str] | None

default:"None"

Ordered parameter names for positional argument mapping. Set automatically by from_function().

Methods

`from_function(fn)`

@classmethod
def from_function(cls, fn: Callable) -> ToolSpec

Extracts a ToolSpec from a Python function using its type hints and docstring. Type mapping:

Python type	JSON Schema type
`str`	`string`
`int`	`integer`
`float`	`number`
`bool`	`boolean`
`list`	`array`
`dict`	`object`

Parameters with default values are marked as optional. Parameters without defaults are required.

def get_user(user_id: str, include_email: bool = False) -> dict:
    """Fetch a user by ID."""
    ...

spec = ToolSpec.from_function(get_user)
# spec.name == "get_user"
# spec.description == "Fetch a user by ID."
# spec.parameters == {
#     "type": "object",
#     "properties": {
#         "user_id": {"type": "string"},
#         "include_email": {"type": "boolean"},
#     },
#     "required": ["user_id"],
# }
# spec.returns == {"type": "object"}

`to_schema()`

def to_schema(self) -> dict

Returns the full schema as a dictionary with name, description, parameters, and returns keys.

`build_input(*args, **kwargs)`

def build_input(self, *args: Any, **kwargs: Any) -> dict

Maps positional and keyword arguments to a dictionary using the parameter names. Used internally by the @world.tool decorator.

spec = ToolSpec.from_function(get_user)
spec.build_input("u1", include_email=True)
# {"user_id": "u1", "include_email": True}

Examples

Manual schema

from rdk.synthetic import ToolSpec

spec = ToolSpec(
    name="create_invoice",
    description="Create an invoice for a customer",
    parameters={
        "type": "object",
        "properties": {
            "customer_id": {"type": "string"},
            "amount": {"type": "number"},
            "currency": {"type": "string"},
        },
        "required": ["customer_id", "amount"],
    },
    returns={
        "type": "object",
        "properties": {
            "invoice_id": {"type": "string"},
            "status": {"type": "string"},
            "created_at": {"type": "string"},
        },
        "required": ["invoice_id", "status"],
    },
)

world.register_tool(spec)
result = world.call("create_invoice", {"customer_id": "c1", "amount": 99.99})

From function

from rdk.synthetic import ToolSpec

def search_orders(customer_id: str, status: str = "all", limit: int = 20) -> list:
    """Search orders by customer and optional status filter."""
    ...

spec = ToolSpec.from_function(search_orders)
print(spec.to_schema())

Core

Synthetic Worlds

Utilities

PII Redaction

Models

Class

Overview

Constructor

Methods

`from_function(fn)`

`to_schema()`

`build_input(*args, **kwargs)`

Examples

Manual schema

From function

See Also

​Class

​Overview

​Constructor

​Methods

​from_function(fn)

​to_schema()

​build_input(*args, **kwargs)

​Examples

​Manual schema

​From function

​See Also

Class

Overview

Constructor

Methods

`from_function(fn)`

`to_schema()`

`build_input(*args, **kwargs)`

Examples

Manual schema

From function

See Also