Create Your First Tool

Once you have set up your local environment and obtained a programmatic API key, you can begin configuring your tool infrastructure. The Tools Registry enables you to store and manage tool definitions, specifying the exact input parameters and expected output structure as JSON Schema specifications. This metadata allows LLM orchestration systems to discover and execute your tools dynamically. Unlike prompts, versions in the Tools Registry manage the evolution of these input and output schemas. This tutorial guides you through creating a project, a tool container, defining input and output schemas, and promoting your first version.

You can also perform all of these actions directly through the user-friendly px0 Web Console at http://localhost:8000. If you prefer configuring your tool infrastructure programmatically using our API, you can follow the detailed step-by-step instructions below.

Prerequisites

Before starting, ensure you have:

Started local services and created an account. See Run px0 Locally for details.
Retrieved your organization and team IDs and generated a programmatic API key. See Get an Access Key for details.

Export your session token and team ID in your terminal:

export PX0_ACCESS_TOKEN="your_session_token"
export PX0_TEAM_ID="your_team_id"

1. Create a Project

Create a project under your team. A project is a named container for your prompts, skills, and tools. Run the following request to create a project:

curl -i -X POST http://localhost:8000/v1/projects \
  -H "Authorization: Bearer ${PX0_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"team_id": "'"${PX0_TEAM_ID}"'", "name": "Main Project", "slug": "main"}'

Save the project ID returned in the JSON response as an environment variable:

export PX0_PROJECT_ID="your_project_id_here"

2. Create a Tool

Create a tool inside your project by sending a POST request containing the name, slug, and description of the tool. Run the following request to create a tool:

curl -i -X POST http://localhost:8000/v1/projects/${PX0_PROJECT_ID}/tools \
  -H "Authorization: Bearer ${PX0_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weather Fetcher", "slug": "weather", "description": "Retrieve current weather information for a given location"}'

Save the tool ID returned in the JSON response as an environment variable:

export PX0_TOOL_ID="your_tool_id_here"

3. Create a Tool Version

Once you have created a tool, initialize a version to define its input and output interfaces. Creating a version establishes a draft with optional input and output JSON Schema specifications. Run the following request to create your first tool version:

curl -i -X POST http://localhost:8000/v1/tools/${PX0_TOOL_ID}/versions \
  -H "Authorization: Bearer ${PX0_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"input_schema": {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}}, "required": ["location"]}, "output_schema": {"type": "object", "properties": {"temperature": {"type": "number"}, "conditions": {"type": "string"}}, "required": ["temperature", "conditions"]}}'

Save the tool version number returned in the JSON response as an environment variable:

export PX0_TOOL_VERSION=1

4. Retrieve and Promote Your Tool Version

Once created, you can retrieve the version schemas or promote the version along the standard lifecycle pipeline: draft to stable, and stable to live.

Option A: Retrieve the Draft Version

Query the detailed schema information of your tool version:

curl -i -X GET http://localhost:8000/v1/tools/${PX0_TOOL_ID}/versions/${PX0_TOOL_VERSION} \
  -H "Authorization: Bearer ${PX0_ACCESS_TOKEN}"

Option B: Promote to Stable and Live

Promote your version to stable to make its schemas immutable:

curl -i -X POST http://localhost:8000/v1/tools/${PX0_TOOL_ID}/versions/${PX0_TOOL_VERSION}/promote \
  -H "Authorization: Bearer ${PX0_ACCESS_TOKEN}"

Promote your version to live to make it active (this automatically demotes any previously live version of this tool to stable):

curl -i -X POST http://localhost:8000/v1/tools/${PX0_TOOL_ID}/versions/${PX0_TOOL_VERSION}/promote \
  -H "Authorization: Bearer ${PX0_ACCESS_TOKEN}"

Next Steps

Now that you have successfully set up local services and managed a tool, you can proceed to configure telemetry to observe your workspace.

Setup Telemetry

Getting Started

SDK

References

Create Your First Tool

Prerequisites

1. Create a Project

2. Create a Tool

3. Create a Tool Version

4. Retrieve and Promote Your Tool Version

Option A: Retrieve the Draft Version

Option B: Promote to Stable and Live

Next Steps

​Prerequisites

​1. Create a Project

​2. Create a Tool

​3. Create a Tool Version

​4. Retrieve and Promote Your Tool Version

​Option A: Retrieve the Draft Version

​Option B: Promote to Stable and Live

​Next Steps

Prerequisites

1. Create a Project

2. Create a Tool

3. Create a Tool Version

4. Retrieve and Promote Your Tool Version

Option A: Retrieve the Draft Version

Option B: Promote to Stable and Live

Next Steps