bilt_list_projects

Overview

Retrieves a list of all projects owned by the authenticated user. Use this tool when you need to discover existing projects or find a specific project by name.

Returns both public and private projects owned by the current API token’s user.

Parameters

This tool takes no parameters. Simply invoke it to get the full project list.

Response

array

required

Array of project objects

Show Project Object

string

required

Unique project identifier (UUID format)

string

required

Project name

string

Project description (null if not set)

string

required

"public" or "private"

string

required

ISO 8601 timestamp of creation

string

required

ISO 8601 timestamp of last update

Example Usage

"Show me all my Bilt projects"

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "todo-app",
      "description": "A simple todo list application",
      "visibility": "public",
      "createdAt": "2026-02-10T10:30:00.000Z",
      "updatedAt": "2026-02-10T14:20:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "landing-page",
      "description": null,
      "visibility": "private",
      "createdAt": "2026-02-09T15:45:00.000Z",
      "updatedAt": "2026-02-09T15:45:00.000Z"
    }
  ]
}

Common Use Cases

1. Find Project by Name

User: "Show me my todo-app project"

Agent workflow:
1. Call bilt_list_projects()
2. Filter results: project.name === "todo-app"
3. Return matching project or "not found"

2. List Recent Projects

User: "What projects have I created today?"

Agent workflow:
1. Call bilt_list_projects()
2. Filter by createdAt date
3. Sort by newest first
4. Display results

3. Check if Project Exists

Before creating a project, check if name is taken:

Agent workflow:
1. Call bilt_list_projects()
2. Check if any project.name matches desired name
3. If exists, suggest alternative name
4. If not, proceed with creation

Response Scenarios

Empty Project List

{
  "projects": []
}

This means the user has no projects yet. Suggest creating one with bilt_create_project.

Single Project

{
  "projects": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "first-app",
      "description": "My first Bilt app",
      "visibility": "public",
      "createdAt": "2026-02-10T15:00:00.000Z",
      "updatedAt": "2026-02-10T15:00:00.000Z"
    }
  ]
}

Multiple Projects

When users have many projects, the array will contain all of them. There’s no automatic pagination - the tool returns everything.

Best Practices

Cache the results

If you need project data multiple times in a conversation, store the results instead of calling repeatedly.

// Pseudo-code
let projectCache = null;

async function getProjects() {
  if (!projectCache) {
    projectCache = await bilt_list_projects();
  }
  return projectCache;
}

Filter client-side

The API returns all projects. Do filtering/sorting on the client:

const projects = await bilt_list_projects();

// Find by name
const todoApp = projects.find(p => p.name === 'todo-app');

// Filter by visibility
const publicProjects = projects.filter(p => p.visibility === 'public');

// Sort by date
projects.sort((a, b) => 
  new Date(b.createdAt) - new Date(a.createdAt)
);

Use for discovery, not iteration

List projects to help users find what they’re looking for, not to perform operations on every project.✅ Good: “Which project do you want to modify?”❌ Avoid: “Let me check every project for errors…”

Present results clearly

When showing project lists to users, format them nicely:

Your projects:
1. todo-app (public) - Created Feb 10
2. landing-page (private) - Created Feb 9
3. dashboard (public) - Created Feb 8

Which one would you like to work on?

Error Handling

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Authentication failed - invalid or expired API key"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded - please slow down requests"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error"
  }
}

Rate Limits

Request Limit100 requests per minute

Best PracticeCache results within a session

Performance

Response time: < 200ms typical
Payload size: ~500 bytes per project
Max projects: 100 per user (free tier)

For users with many projects, consider pagination on the client side when displaying results.

bilt_get_project

Get details of a specific project

bilt_create_project

Create a new project

bilt_send_message

Start working on a project

Next Steps

After listing projects:

Select a project - Use the returned ID with other tools
Get project details - Call bilt_get_project
Start a workflow - Get session with bilt_get_session
Create new project - If list is empty, use bilt_create_project

Get Started

Client Setup

Tools Reference

bilt_list_projects

Overview

Parameters

Response

Example Usage

Common Use Cases

1. Find Project by Name

2. List Recent Projects

3. Check if Project Exists

Response Scenarios

Empty Project List

Single Project

Multiple Projects

Best Practices

Error Handling

Rate Limits

Performance

bilt_get_project

bilt_create_project

bilt_send_message

Next Steps

​Overview

​Parameters

​Response

​Example Usage

​Common Use Cases

​1. Find Project by Name

​2. List Recent Projects

​3. Check if Project Exists

​Response Scenarios

​Empty Project List

​Single Project

​Multiple Projects

​Best Practices

​Error Handling

​Rate Limits

​Performance

​Related Tools

bilt_get_project

bilt_create_project

bilt_send_message

​Next Steps

Overview

Parameters

Response

Example Usage

Common Use Cases

1. Find Project by Name

2. List Recent Projects

3. Check if Project Exists

Response Scenarios

Empty Project List

Single Project

Multiple Projects

Best Practices

Error Handling

Rate Limits

Performance

Related Tools

Next Steps