Tools API

The Tools API provides endpoints for creating, managing, and executing AI tools. Tools are the core building blocks of the MCP Tools & Servers platform — each tool wraps a Nexset as an AI-callable function with a typed schema, versioning, and governance metadata.

Endpoints

Method	Path	Description
POST	`/v1/tools:from_nexset`	Create a tool from a Nexset
GET	`/v1/tools`	List tools
GET	`/v1/tools/{tool_id}`	Get tool details
PATCH	`/v1/tools/{tool_id}`	Update tool metadata
DELETE	`/v1/tools/{tool_id}`	Delete a tool (soft delete)
POST	`/v1/tools/{tool_id}:activate`	Activate a tool
POST	`/v1/tools/{tool_id}:pause`	Pause a tool
POST	`/v1/tools/{tool_id}:execute`	Execute a tool
GET	`/v1/tools/{tool_id}/definition`	Get tool JSON definition
GET	`/v1/tools/{tool_id}/usage`	Get ToolSets using this tool
GET	`/v1/tools/{tool_id}/changelogs`	List changelog entries
POST	`/v1/tools:reconcile`	Reconcile tools from Nexsets

All endpoints require authentication via a service key. See Authentication for details.

Create a Tool from a Nexset

POST /v1/tools:from_nexset

Creates a new tool backed by an existing Nexset. The tool inherits its schema from the Nexset's data contract.

Request:

curl -X POST https://api-genai.nexla.io/v1/tools:from_nexset \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nexset_id": 12345,
    "publish": true
  }'

Request body:

Field	Type	Required	Description
`nexset_id`	integer	Yes	The ID of the Nexset to create the tool from
`publish`	boolean	No	If `true`, the tool is activated immediately. Defaults to `false`.

Response (201 Created):

{
  "id": 1,
  "key": "read_customer_orders",
  "name": "Read Customer Orders",
  "kind": "nexset_read",
  "status": "active",
  "version": "1.0.0",
  "contract_hash": "a1b2c3...",
  "data_set_id": 12345,
  "created_at": "2025-01-15T10:30:00Z"
}

note

If publish is false, the tool is created with status init and must be activated separately via POST /v1/tools/{tool_id}:activate.

List Tools

GET /v1/tools

Returns a paginated list of tools in the caller's organization.

Query parameters:

Parameter	Type	Description
`status`	string	Filter by status: `active`, `paused`, or `init`
`kind`	string	Filter by kind: `nexset_read`, `nexset_action`, or `custom_tool`
`search`	string	Full-text search across tool name, key, and description
`tags`	string	Comma-separated list of tags to filter by
`sort`	string	Sort field: `created_at` or `updated_at`
`order`	string	Sort direction: `asc` or `desc`
`limit`	integer	Page size (max 200)
`offset`	integer	Number of records to skip

Example request:

curl -X GET "https://api-genai.nexla.io/v1/tools?status=active&kind=nexset_read&limit=50&offset=0" \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200 OK):

[
  {
    "id": 1,
    "key": "read_customer_orders",
    "name": "Read Customer Orders",
    "kind": "nexset_read",
    "status": "active",
    "version": "1.0.0",
    "tags": ["sales", "orders"],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  {
    "id": 2,
    "key": "write_inventory_update",
    "name": "Write Inventory Update",
    "kind": "nexset_action",
    "status": "active",
    "version": "2.1.0",
    "tags": ["inventory"],
    "created_at": "2025-01-14T08:00:00Z",
    "updated_at": "2025-01-16T14:22:00Z"
  }
]

Get Tool Details

GET /v1/tools/{tool_id}

Returns the full metadata for a single tool, including its embedded tool_definition.

Example request:

curl -X GET https://api-genai.nexla.io/v1/tools/1 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200 OK):

{
  "id": 1,
  "key": "read_customer_orders",
  "name": "Read Customer Orders",
  "description": "Retrieve customer order records with optional filters",
  "kind": "nexset_read",
  "status": "active",
  "version": "1.0.0",
  "contract_hash": "a1b2c3...",
  "data_set_id": 12345,
  "tags": ["sales", "orders"],
  "tool_definition": {
    "input_schema": { "..." : "..." },
    "output_schema": { "..." : "..." }
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Update Tool Metadata

PATCH /v1/tools/{tool_id}

Updates mutable fields on a tool. Only the fields included in the request body are modified.

Example request:

curl -X PATCH https://api-genai.nexla.io/v1/tools/1 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Tool Name",
    "description": "New description",
    "tags": ["sales", "reporting"]
  }'

Request body:

Field	Type	Description
`name`	string	Display name for the tool
`description`	string	Human-readable description
`tags`	array	List of string tags for filtering and organization

Response (200 OK): Returns the updated tool object.

Delete a Tool

DELETE /v1/tools/{tool_id}

Soft-deletes a tool. The tool is marked as deleted and removed from any ToolSets, but its data is retained for audit purposes.

curl -X DELETE https://api-genai.nexla.io/v1/tools/1 \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response: 204 No Content

Activate a Tool

POST /v1/tools/{tool_id}:activate

Transitions a tool from init or paused status to active. Active tools are available for execution and visible in ToolSets.

curl -X POST https://api-genai.nexla.io/v1/tools/1:activate \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200 OK): Returns the updated tool object with "status": "active".

Pause a Tool

POST /v1/tools/{tool_id}:pause

Pauses an active tool. Paused tools cannot be executed but remain in their ToolSets.

curl -X POST https://api-genai.nexla.io/v1/tools/1:pause \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200 OK): Returns the updated tool object with "status": "paused".

Execute a Tool

POST /v1/tools/{tool_id}:execute

Executes a tool and returns the result. Each execution is recorded with a unique receipt ID for auditing.

Example request:

curl -X POST https://api-genai.nexla.io/v1/tools/1:execute \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "args": {
      "format": "dataframe_columns",
      "limit": 100
    }
  }'

Request body:

Field	Type	Required	Description
`version`	string	No	Tool version to execute. Defaults to the latest version.
`args`	object	No	Input arguments matching the tool's input schema

Response (200 OK):

{
  "receipt_id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "status": "ok",
    "data": ["..."],
    "row_count": 42,
    "truncated": false
  }
}

warning

Tool execution requires operator role on the associated Nexset. Execution is rate-limited per principal.

Get Tool Definition

GET /v1/tools/{tool_id}/definition

Returns the full ToolDefinitionV1 JSON schema for the tool, including input/output schemas, execution bindings, and governance metadata. This is the definition that MCP clients receive when they discover the tool through a ToolSet's MCP server.

Example request:

curl -X GET https://api-genai.nexla.io/v1/tools/1/definition \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Response (200 OK):

{
  "name": "read_customer_orders",
  "description": "Retrieve customer order records with optional filters",
  "version": "1.0.0",
  "input_schema": {
    "type": "object",
    "properties": {
      "format": {
        "type": "string",
        "enum": ["dataframe_columns", "json_records"]
      },
      "limit": {
        "type": "integer",
        "default": 100,
        "maximum": 10000
      }
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "data": { "type": "array" },
      "row_count": { "type": "integer" },
      "truncated": { "type": "boolean" }
    }
  },
  "governance": {
    "contract_hash": "a1b2c3...",
    "data_set_id": 12345
  }
}

Get Tool Usage

GET /v1/tools/{tool_id}/usage

Returns the list of ToolSets that include this tool.

curl -X GET https://api-genai.nexla.io/v1/tools/1/usage \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Get Tool Changelogs

GET /v1/tools/{tool_id}/changelogs

Returns a chronological list of changelog entries for the tool, including version bumps, status changes, and metadata updates.

curl -X GET https://api-genai.nexla.io/v1/tools/1/changelogs \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY"

Reconcile Tools

POST /v1/tools:reconcile

Batch operation that scans Nexsets modified since the given timestamp and creates or updates tools accordingly. This is useful for keeping tools in sync with upstream Nexset schema changes.

Example request:

curl -X POST https://api-genai.nexla.io/v1/tools:reconcile \
  -H "Authorization: Bearer $NEXLA_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2025-01-01T00:00:00Z"
  }'

Request body:

Field	Type	Required	Description
`since`	string (ISO 8601)	Yes	Only reconcile Nexsets modified after this timestamp

Response (200 OK):

{
  "scanned": 150,
  "created": 12,
  "updated_versions": 5,
  "unchanged": 133
}

Field	Description
`scanned`	Total number of Nexsets evaluated
`created`	New tools created from Nexsets that had no existing tool
`updated_versions`	Existing tools whose version was bumped due to schema changes
`unchanged`	Nexsets whose tools were already up to date

Endpoints​

Create a Tool from a Nexset​

List Tools​

Get Tool Details​

Update Tool Metadata​

Delete a Tool​

Activate a Tool​

Pause a Tool​

Execute a Tool​

Get Tool Definition​

Get Tool Usage​

Get Tool Changelogs​

Reconcile Tools​

Endpoints

Create a Tool from a Nexset

List Tools

Get Tool Details

Update Tool Metadata

Delete a Tool

Activate a Tool

Pause a Tool

Execute a Tool

Get Tool Definition

Get Tool Usage

Get Tool Changelogs

Reconcile Tools