Tools Overview

Tools are the foundational building blocks of Nexla's MCP Tools & Servers platform. Each tool is a structured API contract that defines how an AI agent can interact with your data -- what parameters it needs to provide, what data it receives back, and how the execution works under the hood. This page explains the core concepts behind tools and how they fit into the broader MCP Tools & Servers workflow.

What Are Tools?

A tool is an AI-callable interface auto-generated from a Nexla Nexset. When you create a tool, Nexla inspects the underlying Nexset's structure and metadata, then produces a complete tool definition that follows the Model Context Protocol (MCP) specification. This definition includes everything an AI agent needs to discover the tool, understand its purpose, construct valid requests, and interpret the results.

Because tools are generated from Nexsets, they inherit the schema, data types, and access patterns of the source data. If the Nexset represents a database table, the tool provides a structured way to query that table. If the Nexset represents an API endpoint, the tool wraps that endpoint in a standardized contract. The result is a uniform interface that any MCP-compatible agent -- Claude Desktop, Cursor, ChatGPT, or a custom agent -- can consume without needing to know the specifics of the underlying data source.

Tool Kinds

Every tool has a kind that describes its high-level purpose. The kind determines the tool's default execution semantics and how AI agents should interact with it.

Kind	Description	Use Case
nexset_read	Reads data from a Nexset. Returns records without modifying the source.	AI agents querying and retrieving data -- the most common tool type.
nexset_action	Performs a write or action operation against a Nexset.	AI agents that need to send, update, or transform data.
custom_tool	A manually defined tool with custom logic and configuration.	Specialized operations that do not map directly to a single Nexset.

note

Most tools generated through the standard workflow are nexset_read tools. The nexset_action kind is used when the source Nexset supports write operations, and custom_tool is reserved for advanced use cases.

Tool Lifecycle

Tools follow a defined lifecycle represented by their status. Understanding the status flow helps you manage when tools are available to AI agents and when they are not.

init  ──────►  active  ◄──────►  paused
(draft)       (published)       (disabled)
                  │
                  ▼
              (deleted)

• init -- The tool has been created but is not yet published. It exists as a draft. Tools in init status are not available for inclusion in ToolSets or for execution by AI agents.
• active -- The tool is published and fully operational. Active tools can be added to ToolSets, deployed via MCP Servers, and invoked by AI agents.
• paused -- The tool has been temporarily disabled. It remains registered in the system and in any ToolSets that reference it, but it will not execute when called. Pausing is useful for temporarily taking a tool offline without removing it from your configuration.
• Deleted -- A soft delete removes the tool from active use. The tool and its history are preserved for audit purposes, but it is no longer available for use.

tip

Use paused status when you need to temporarily disable a tool -- for example, during maintenance on the underlying data source. This avoids the need to remove and re-add the tool to ToolSets.

Versioning

Tools use semantic versioning (major.minor.patch) to track changes over time. When a tool's definition changes -- for example, because the underlying Nexset's schema was modified -- a new version is created automatically.

The versioning system uses two content hashes to detect changes:

• contract_hash -- A SHA-256 hash of the full tool definition (excluding non-semantic fields). Any change to the tool's behavior, schemas, semantics, or execution bindings produces a new contract hash.
• schema_hash -- A SHA-256 hash of just the input, record, and output schemas. Schema-only changes (such as adding or removing fields) produce a new schema hash.

Version bumps follow standard semantic versioning rules:

Change Type	Version Bump	Example
Breaking change (field removed, type changed, required field added)	Major (e.g., 1.0.0 to 2.0.0)	A required column is removed from the Nexset
Backward-compatible addition (new optional field, expanded enum)	Minor (e.g., 1.0.0 to 1.1.0)	A new optional column is added to the Nexset
Non-breaking metadata or patch change	Patch (e.g., 1.0.0 to 1.0.1)	Tool description updated; execution timeout adjusted

Each tool tracks three version references:

• Default version -- The version that ToolSets and MCP Servers use by default.
• Latest version -- The most recently created version, regardless of status.
• Latest published version -- The most recent version with a published status.

Tool Definition Structure

Every tool is backed by a tool definition -- a JSON document that fully describes the tool's contract. The definition follows the tooldef.v1 schema and contains the following sections:

• tool -- Core metadata including the tool's display name, description, kind, tags, and references to the source Nexset (resource_refs).
• version -- Version information including the semantic version string, version status (draft, published, deprecated, retired), content hashes, and compatibility assessments.
• schemas -- JSON Schema definitions for:
  • input -- The parameters an AI agent must provide when calling the tool.
  • record -- The schema of a single data record returned by the tool.
  • output -- The full response envelope, including metadata and the record data.
• semantics -- Execution semantics describing the operation type (read or action), side effects (none, idempotent, non_idempotent), result shape (single, list, paged_list), and performance hints (latency, freshness, rate limits).
• execution -- How the tool is invoked, including the execution mode (sync or async) and one or more execution bindings that specify the protocol, HTTP method, URI template, and timeout.
• auth -- Authentication and authorization requirements, including the caller identity contract and required scopes.
• governance -- Data governance configuration including access policies, data classification, audit settings, and provenance capture.

note

You do not need to write or edit tool definitions manually. Nexla generates the full definition automatically when you create a tool from a Nexset. The definition is available for inspection in the Contract tab of the tool detail view.

Next Steps

• Create & Manage Tools -- Learn how to generate tools from Nexsets, browse the Tools Registry, manage tool metadata, and control the tool lifecycle.
• Tools API -- Programmatically create, list, update, and delete tools via the REST API.
• ToolSets -- Organize tools into deployable collections.
• Getting Started -- Walk through the complete end-to-end workflow from Nexset to connected AI agent.