---
title: "Register session-scoped client tools into the unified index"
method: POST
path: "/v1/tools/register-client-catalog"
tags: ["Tools"]
---

# Register session-scoped client tools into the unified index

`POST /v1/tools/register-client-catalog`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/tools/register-client-catalog`
- Auth: HTTP bearer

Merges Angular- (or other client-) defined tools into the embedding index
for a given `session_id`. Accepts up to 200 items per call. Names are
deduplicated (last-wins at the first-seen position) so repeat-registrations
don't conflict with the embedding-index validator. A divergent name re-use
across sessions returns 409.

## Request body

- RegisterClientCatalogRequest
  - `session_id` string, required
  - `items` ClientToolEntry[], required
    - `name` string, required
    - `description` string, required
    - `when_to_use` string, required
    - `category` string, required
    - `token_cost` integer, required

## Response `200`

Catalog registered

- RegisterClientCatalogResponse
  - `status` 'registered', required
  - `indexed` integer, required: Number of items merged into the unified index for this session.

## Other responses

- `400`: Invalid request
- `409`: Catalog conflict — name already registered with a divergent definition
- `500`: Index rebuild failed
- `503`: ToolGate service not available

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)