Skip to main content

​
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,
)
​
name
string
required
Tool name. Used as the identifier in world.call().
​
description
string
required
Human-readable description of what the tool does.
​
parameters
dict
required
JSON Schema for the tool’s input parameters.
​
returns
dict
required
JSON Schema for the tool’s return value.
​
param_names
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 typeJSON Schema type
strstring
intinteger
floatnumber
boolboolean
listarray
dictobject
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())

​
See Also