# How Tools Are Defined and Registered in the SimStudio AI Tools Registry

> Learn how SimStudio AI registers tools by defining TypeScript modules with Zod schemas, OAuth, and HTTP logic in apps/sim/tools/. Explore the central TOOL_REGISTRY map.

- Repository: [Sim/sim](https://github.com/simstudioai/sim)
- Tags: how-to-guide
- Published: 2026-05-02

---

**SimStudio AI registers external integrations as TypeScript modules in a central `TOOL_REGISTRY` map, where each tool defines its Zod schemas, OAuth requirements, and HTTP request logic in `apps/sim/tools/<service>/` before being imported into [`apps/sim/tools/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/tools/registry.ts).**

The `simstudioai/sim` repository implements a modular tool system that treats every third-party integration—such as Zoom, Google BigQuery, and Cal.com—as a self-contained TypeScript module. Each tool declares its configuration, validation schemas, and API logic in dedicated files under `apps/sim/tools/`, then exports through an index file to the central registry. This architecture enables type-safe workflow execution and straightforward registration of new capabilities.

## Tool Configuration Structure

Individual tools are defined as `ToolConfig` objects that encapsulate everything the workflow engine needs to execute an external API call. Each tool resides in its own subdirectory under `apps/sim/tools/<service>/` and exports a configuration object from a concrete implementation file.

A tool definition includes:

- **`id`**: A unique namespaced identifier (e.g., `zoom.create_meeting`)
- **`params`**: A Zod schema validating input fields from the workflow block
- **`oauth`**: Authentication requirements specifying the provider and scope
- **`request`**: HTTP method, URL, headers, and body construction logic
- **`transformResponse`**: Optional function to reshape API responses for downstream blocks

Here is the Zoom create meeting tool defined in [`apps/sim/tools/zoom/create_meeting.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/tools/zoom/create_meeting.ts):

```typescript
import { z } from 'zod'
import type { ToolConfig } from '@/tools/types'

export const createMeetingTool: ToolConfig = {
  id: 'zoom.create_meeting',
  name: 'Create Zoom Meeting',
  description: 'Creates a new Zoom meeting for a given host.',
  version: '1.0.0',
  oauth: { required: true, provider: 'zoom' },

  params: z.object({
    topic: z.string().min(1, 'Topic must not be empty'),
    start_time: z.string().datetime(),
    duration: z.number().int().positive(),
  }),

  request: {
    method: 'POST',
    url: '/v2/users/me/meetings',
    body: (input) => ({
      topic: input.topic,
      type: 2,
      start_time: input.start_time,
      duration: input.duration,
    }),
  },

  transformResponse: async (response) => ({
    meetingId: response.id,
    joinUrl: response.join_url,
  }),
}

```

## The Registration Pattern

Tools are registered through a two-level export pattern that isolates implementation details from the central registry.

### Service-Level Index Files

Each service folder contains an [`index.ts`](https://github.com/simstudioai/sim/blob/main/index.ts) that re-exports concrete tool configurations under stable names. For example, [`apps/sim/tools/zoom/index.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/tools/zoom/index.ts) exports the create meeting tool:

```typescript
// apps/sim/tools/zoom/index.ts
export { createMeetingTool as zoomCreateMeeting } from './create_meeting'

```

### Central Registry Population

The [`apps/sim/tools/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/tools/registry.ts) file imports these exports and assembles them into `TOOL_REGISTRY`, a constant `Record<string, ToolConfig>` that serves as the runtime lookup table. The registry enforces alphabetical ordering by tool ID to maintain consistency and simplify automated validation.

```typescript
// apps/sim/tools/registry.ts
import { zoomCreateMeeting } from '@/tools/zoom'
import { googleBigQueryQuery } from '@/tools/google_bigquery'
import { calComCreateBooking } from '@/tools/calcom'

export const TOOL_REGISTRY = {
  'calcom.create_booking': calComCreateBooking,
  'google_bigquery.query': googleBigQueryQuery,
  'zoom.create_meeting': zoomCreateMeeting,
} as const

```

When a workflow block references a tool ID, the executor retrieves the corresponding `ToolConfig` from this map to access validation schemas and request definitions.

## Runtime Tool Resolution

During workflow execution, the system resolves tool configurations through the registry map. Functions like `getToolConfig(id)` in the workflow executor import `TOOL_REGISTRY` and return the matching configuration for the requested tool ID.

```typescript
// apps/sim/tools/workflow/executor.ts (conceptual)
import { TOOL_REGISTRY } from '@/tools/registry'

export function getToolConfig(id: string) {
  const tool = TOOL_REGISTRY[id]
  if (!tool) throw new Error(`Tool ${id} not found in registry`)
  return tool
}

```

The executor uses this configuration to:

1. Validate input parameters against the tool's Zod schema
2. Construct the HTTP request using the tool's `request` definition
3. Execute the API call with OAuth credentials if required
4. Apply `transformResponse` to shape the output for subsequent blocks

## Registry Maintenance and Validation

The repository includes automated checks to ensure registry integrity. The script [`apps/sim/scripts/check-block-registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/scripts/check-block-registry.ts) validates that:

1. All entries in `TOOL_REGISTRY` follow strict alphabetical ordering by key
2. Every tool folder under `apps/sim/tools/` has a corresponding entry in the registry
3. No duplicate tool IDs exist in the map

This CI enforcement prevents merge conflicts and ensures that the runtime lookup table remains predictable and complete.

## Summary

- **Tool definition**: Each integration is a `ToolConfig` object in `apps/sim/tools/<service>/<action>.ts` containing Zod schemas, OAuth config, and request logic.
- **Export pattern**: Service-level [`index.ts`](https://github.com/simstudioai/sim/blob/main/index.ts) files re-export tools to provide stable import targets for the registry.
- **Central registration**: [`apps/sim/tools/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/tools/registry.ts) exports `TOOL_REGISTRY`, a strictly ordered `Record<string, ToolConfig>` mapping tool IDs to configurations.
- **Runtime lookup**: The workflow executor imports `TOOL_REGISTRY` to resolve tool configurations by ID during block execution.
- **Automated validation**: [`apps/sim/scripts/check-block-registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/scripts/check-block-registry.ts) enforces alphabetical ordering and completeness in CI.

## Frequently Asked Questions

### How do I add a new tool to the SimStudio AI registry?

Create a new tool configuration file in `apps/sim/tools/<service>/<action>.ts` implementing the `ToolConfig` interface with your Zod schemas and request logic. Export it from `apps/sim/tools/<service>/index.ts`, then import and add it to the `TOOL_REGISTRY` object in [`apps/sim/tools/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/tools/registry.ts) following alphabetical order by tool ID.

### What happens if a tool is not found in the registry at runtime?

The workflow executor calls `getToolConfig(id)` which accesses `TOOL_REGISTRY[id]`. If the ID does not exist in the map, the function throws an error indicating the tool was not found, preventing execution of undefined tools.

### Why does the registry enforce alphabetical ordering?

Alphabetical ordering in `TOOL_REGISTRY` prevents merge conflicts when multiple developers add tools simultaneously and enables the [`check-block-registry.ts`](https://github.com/simstudioai/sim/blob/main/check-block-registry.ts) script to perform deterministic validation. The CI script checks this ordering automatically on every pull request.

### What is the purpose of the `transformResponse` field in ToolConfig?

The `transformResponse` function allows tools to reshape raw API responses into a standardized format before passing data to downstream workflow blocks. This abstraction ensures that workflow users receive consistent field names and data structures regardless of third-party API conventions.