> ## Documentation Index
> Fetch the complete documentation index at: https://docs.px0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Your First Tool

> Step-by-step tutorial on creating a project, tool container, defining input and output schemas, and managing version lifecycles.

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.

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

## Prerequisites

Before starting, ensure you have:

* Started local services and created an account. See [Run px0 Locally](/get-started/run-locally) for details.
* Retrieved your organization and team IDs and generated a programmatic API key. See [Get an Access Key](/get-started/get-access-key) for details.

Export your session token and team ID in your terminal:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
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](/get-started/setup-telemetry)