Careeroza

Defining a Tool Schema

Name, Description, Input Schema

A tool definition has a name, a description (when and why to use it: the model relies on this) and an input_schema (JSON Schema for the arguments).

{
  "name": "get_order_status",
  "description": "Get the live status of a ShopEase order. Call this whenever the customer asks where their order is, when it will arrive, or whether it shipped.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "Order ID like SE-10423"}
    },
    "required": ["order_id"]
  }
}

Generating a Schema from a Python Function

Example

SDK helpers (like the Anthropic SDK's @beta_tool decorator) build the schema from the function's type hints and docstring. This is roughly how, using inspect:

import inspect, json

def create_return(order_id: str, reason: str, pickup: bool = True) -> str:
    """Create a return request for a delivered ShopEase order. Use only after the customer confirms."""
    return f"RET-{order_id[-4:]}"

PY_TO_JSON = {str: "string", int: "integer", float: "number", bool: "boolean"}

def tool_schema(fn):
    sig = inspect.signature(fn)
    props, required = {}, []
    for name, param in sig.parameters.items():
        props[name] = {"type": PY_TO_JSON[param.annotation]}
        if param.default is inspect.Parameter.empty:
            required.append(name)
    return {"name": fn.__name__, "description": inspect.getdoc(fn),
            "input_schema": {"type": "object", "properties": props, "required": required}}

print(json.dumps(tool_schema(create_return), indent=2))

Output

{
  "name": "create_return",
  "description": "Create a return request for a delivered ShopEase order. Use only after the customer confirms.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string"
      },
      "reason": {
        "type": "string"
      },
      "pickup": {
        "type": "boolean"
      }
    },
    "required": [
      "order_id",
      "reason"
    ]
  }
}

Tip: Write descriptions that say when to call the tool, not just what it does. Keep the number of tools small and their names distinct (get_order_status vs search_products).