Tutorial 1: Getting started with toolschema¶
Time: 10 minutes
Prerequisites: Python 3.10+, uv
toolschema turns a typed Python function into JSON Schema for any AI agent provider — once, without framework lock-in.
Install¶
uv add toolschema
# or with integrations:
uv add "toolschema[fastmcp,langchain]"
Define a tool¶
from typing import Annotated
from toolschema import Field, schema, tool
@tool
def get_weather(
city: Annotated[str, Field(description="City name", min_length=1)],
units: str = "celsius",
) -> dict:
"""Get current weather for a city."""
return {"city": city, "temp": 22, "units": units}
Export schemas¶
definition = schema(get_weather)
definition.parameters # canonical JSON Schema 2020-12
definition.to_openai() # OpenAI function-calling
definition.to_openai(strict=True) # OpenAI strict mode
definition.to_mcp() # MCP inputSchema (+ outputSchema)
definition.to_anthropic() # Anthropic input_schema
definition.to_gemini() # Gemini FunctionDeclaration
Validate arguments (Pre-PEP aligned)¶
result = definition.validate({"city": "Paris"})
if result.issues:
for issue in result.issues:
print(issue.message)
else:
print(result.value) # defaults filled in
Standard Schema interop¶
Ecosystem tools that support Standard Schema can consume toolschema without custom adapters:
from toolschema import JSONSchemaOptions
standard = definition.standard["~standard"]
input_schema = standard["jsonSchema"]["input"](JSONSchemaOptions(target="draft-2020-12"))
validated = standard["validate"]({"city": "Tokyo"})
CLI inspect¶
uv run toolschema inspect myapp.tools:get_weather --format mcp
uv run toolschema diff myapp.tools:get_weather --targets openai,mcp