Add Tools

---
name: add-tools
description: Create tool configurations for a Sim integration by reading API docs
argument-hint: <service-name> [api-docs-url]
---

# Add Tools Skill

You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files.

## Your Task

When the user asks you to create tools for a service:
1. Use Context7 or WebFetch to read the service's API documentation
2. Create the tools directory structure
3. Generate properly typed tool configurations

## Hard Rule: No Guessed Response Schemas

If the docs do not clearly show the response JSON for a tool, you MUST tell the user exactly which outputs are unknown and stop short of guessing.

- Do NOT invent response field names
- Do NOT infer nested paths from nearby endpoints
- Do NOT guess array item shapes
- Do NOT write `transformResponse` against unverified payloads

If the response shape is unknown, do one of these instead:
1. Ask the user for sample responses
2. Ask the user for test credentials so you can verify live responses
3. Implement only the endpoints whose outputs are documented
4. Leave the tool unimplemented and explicitly say why

## Directory Structure

Create files in `apps/sim/tools/{service}/`:
```
tools/{service}/
├── index.ts      # Barrel export
├── types.ts      # Parameter & response types
└── {action}.ts   # Individual tool files (one per operation)
```

## Tool Configuration Structure

### Choose the execution boundary first

Every tool must use exactly one of these configurations:

- **In-process operation (preferred):** use `InternalToolConfig` when the executor and the
  implementation run in the same Sim process/trust/runtime plane. Materialize typed
  `operation.input`, implement the handler under `apps/sim/lib/internal/{service}/execute-tool.ts`,
  and register every tool ID in `apps/sim/lib/internal/tool-operations/registry.server.ts`.
- **External provider request:** use `ToolConfig.request` only when the URL is an absolute external
  HTTP(S) provider endpoint.

Never set a tool URL to `/api/...`, construct an absolute URL back to Sim, declare
`request.internal`, add the retired `directExecution` property, import a route module, or create an API route merely to normalize files,
authorize access, or reuse server code. A real browser/API route may remain as a thin adapter, but
the route and the tool must call the same operation directly. A true cross-process/capability
boundary uses an explicit server client and is not disguised as a tool self-hop.

For protected Sim resources, the internal handler calls the domain's authorized application use
case with trusted execution context; use the `migrate-application-operation` skill.

### External provider request

Use this structure only for an absolute external provider API:

```typescript
import type { {ServiceName}{Action}Params } from '@/tools/{service}/types'
import type { ToolConfig } from '@/tools/types'

interface {ServiceName}{Action}Response {
  success: boolean
  output: {
    // Define output structure here
  }
}

export const {serviceName}{Action}Tool: ToolConfig<
  {ServiceName}{Action}Params,
  {ServiceName}{Action}Response
> = {
  id: '{service}_{action}',           // snake_case, matches tool name
  name: '{Service} {Action}',         // Human readable
  description: 'Brief description',   // One sentence
  version: '1.0.0',

  // OAuth config (if service uses OAuth)
  oauth: {
    required: true,
    provider: '{service}',            // Must match OAuth provider ID
  },

  params: {
    // Hidden params (system-injected, only use hidden for oauth accessToken)
    accessToken: {
      type: 'string',
      required: true,
      visibility: 'hidden',
      description: 'OAuth access token',
    },
    // User-only params (credentials, api key, IDs user must provide)
    someId: {
      type: 'string',
      required: true,
      visibility: 'user-only',
      description: 'The ID of the resource',
    },
    // User-or-LLM params (everything else, can be provided by user OR computed by LLM)
    query: {
      type: 'string',
      required: false,                // Use false for optional
      visibility: 'user-or-llm',
      description: 'Search query',
    },
  },

  request: {
    url: (params) => `https://api.service.com/v1/resource/${params.id}`,
    method: 'POST',
    headers: (params) => ({
      Authorization: `Bearer ${params.accessToken}`,
      'Content-Type': 'application/json',
    }),
    body: (params) => ({
      // Request body - only for POST/PUT/PATCH
      // Trim ID fields to prevent copy-paste whitespace errors:
      // userId: params.userId?.trim(),
    }),
  },

  transformResponse: async (response: Response) => {
    const data = await response.json()
    return {
      success: true,
      output: {
        // Map API response to output
        // Use ?? null for nullable fields
        // Use ?? [] for optional arrays
      },
    }
  },

  outputs: {
    // Define each output field
  },
}
```

### In-process operation

```typescript
import type { InternalToolConfig } from '@/tools/types'

export const {serviceName}{Action}Tool: InternalToolConfig<
  {ServiceName}{Action}Params,
  {ServiceName}{Action}Response
> = {
  id: '{service}_{action}',
  name: '{Service} {Action}',
  description: 'Brief description',
  version: '1.0.0',
  params: {
    // Same canonical metadata as an external tool.
  },
  operation: {
    input: (params) => ({
      // Map resolved tool params into the typed semantic operation input.
    }),
  },
  outputs: {
    // Define each output field.
  },
}
```

The registered handler accepts `InternalToolOperationCall`, validates `request.input`, uses only
trusted `request.context` for authority, forwards `request.signal`, and returns the same bounded
`Response` contract expected by the tool executor. It has no URL, method, request headers, fetch
fallback, or caller-controlled `_context` authority.

## Critical Rules for Parameters

### Visibility Options
- `'hidden'` - System-injected (OAuth tokens, internal params). User never sees.
- `'user-only'` - User must provide (credentials, api keys, account-specific IDs)
- `'user-or-llm'` - User provides OR LLM can compute (search queries, content, filters, most fall into this category)

### Parameter Types
- `'string'` - Text values
- `'number'` - Numeric values
- `'boolean'` - True/false
- `'json'` - Complex objects (NOT 'object', use 'json')
- `'file'` - Single file
- `'file[]'` - Multiple files

### Required vs Optional
- Always explicitly set `required: true` or `required: false`
- Optional params should have `required: false`

## Resolved Secrets and Provenance Boundaries

- Leave ordinary external API inputs and third-party results unchanged. Add provenance handling only
  when an exact field is proven to cross a Sim model, durable-storage, or internal-execution boundary.
- Project AI-consumed text/structured fields with the smallest exact model-input selector:
  `request.modelInput` for an external request or `operation.modelInput` for an in-process operation.
- Treat URLs, domains, resource IDs, and control fields as ordinary request values unless the exact
  field is proven model-visible. For serialized external model content, project the serialized
  top-level param through `request.modelInput` before the existing formatter parses it; do not add a
  separate hard-rejection mechanism.
- For in-process operations, use `operation.modelInput` for actual inline/raw model bytes or
  `operation.secretProvenance` for durable writes and execution handoffs. Do not treat a storage key,
  path, signed URL, or remote URL as provenance for fetched bytes; authorize tracked stored bytes at
  the owning model-egress boundary. Validate the exact selection and trusted scope, then import or
  propagate provenance at the receiving operation boundary.
- Never substitute secret plaintext into source, serialize plaintext provenance, hand-roll private
  headers, or blanket-sanitize tool results.
- Add focused tests for named projection, identical unproven public text, malformed/incomplete
  metadata, metadata stripping, scope isolation, and legacy compatibility where applicable.

## Critical Rules for Outputs

### Output Types
- `'string'`, `'number'`, `'boolean'` - Primitives
- `'json'` - Complex objects (use this, NOT 'object')
- `'array'` - Arrays with `items` property
- `'object'` - Objects with `properties` property

### Optional Outputs
Add `optional: true` for fields that may not exist in the response:
```typescript
closedAt: {
  type: 'string',
  description: 'When the issue was closed',
  optional: true,
},
```

### Typed JSON Outputs

When using `type: 'json'` and you know the object shape in advance, **always define the inner structure** using `properties` so downstream consumers know what fields are available:

```typescript
// BAD: Opaque json with no info about what's inside
metadata: {
  type: 'json',
  description: 'Response metadata',
},

// GOOD: Define the known properties
metadata: {
  type: 'json',
  description: 'Response metadata',
  properties: {
    id: { type: 'string', description: 'Unique ID' },
    status: { type: 'string', description: 'Current status' },
    count: { type: 'number', description: 'Total count' },
  },
},
```

For arrays of objects, define the item structure:
```typescript
items: {
  type: 'array',
  description: 'List of items',
  items: {
    type: 'object',
    properties: {
      id: { type: 'string', description: 'Item ID' },
      name: { type: 'string', description: 'Item name' },
    },
  },
},
```

Only use bare `type: 'json'` without `properties` when the shape is truly dynamic or unknown.

If the response shape is unknown because the docs do not provide it, you MUST tell the user and stop. Unknown is not the same as dynamic. Never guess outputs.

## Critical Rules for transformResponse

### Handle Nullable Fields
ALWAYS use `?? null` for fields that may be undefined:
```typescript
transformResponse: async (response: Response) => {
  const data = await response.json()
  return {
    success: true,
    output: {
      id: data.id,
      title: data.title,
      body: data.body ?? null,           // May be undefined
      assignee: data.assignee ?? null,   // May be undefined
      labels: data.labels ?? [],         // Default to empty array
      closedAt: data.closed_at ?? null,  // May be undefined
    },
  }
}
```

### Never Output Raw JSON Dumps
DON'T do this:
```typescript
output: {
  data: data,  // BAD - raw JSON dump
}
```

DO this instead - extract meaningful fields:
```typescript
output: {
  id: data.id,
  name: data.name,
  status: data.status,
  metadata: {
    createdAt: data.created_at,
    updatedAt: data.updated_at,
  },
}
```

## Types File Pattern

Create `types.ts` with interfaces for all params and responses:

```typescript
import type { ToolResponse } from '@/tools/types'

// Parameter interfaces
export interface {Service}{Action}Params {
  accessToken: string
  requiredField: string
  optionalField?: string
}

// Response interfaces (extend ToolResponse)
export interface {Service}{Action}Response extends ToolResponse {
  output: {
    field1: string
    field2: number
    optionalField?: string | null
  }
}
```

## Index.ts Barrel Export Pattern

```typescript
// Export all tools
export { serviceTool1 } from './{action1}'
export { serviceTool2 } from './{action2}'

// Export types
export * from './types'
```

## Registering Tools

After creating tools:
1. Import tools in `apps/sim/tools/registry.ts`
2. Add to the `tools` object with snake_case keys (alphabetically):
```typescript
import { serviceActionTool } from '@/tools/{service}'

export const tools = {
  // ... existing tools ...
  {service}_{action}: serviceActionTool,
}
```

3. Regenerate the tool metadata artifacts:

```bash
bun run tool-metadata:generate
```

Client code reads a tool's `params`/`outputs` from generated metadata rather than
importing the registry, so a tool you add, change or remove is invisible to the UI until
these are regenerated — and CI fails on stale artifacts. Commit the result. See
`.agents/skills/tool-registry-boundary/SKILL.md`.

## Wiring Tools into the Block (Required)

After registering in `tools/registry.ts`, you MUST also update the block definition at `apps/sim/blocks/blocks/{service}.ts`. This is not optional — tools are only usable from the UI if they are wired into the block.

### 1. Add to `tools.access`

```typescript
tools: {
  access: [
    // existing tools...
    'service_new_action',   // Add every new tool ID here
  ],
  config: { ... }
}
```

### 2. Add operation dropdown options

If the block uses an operation dropdown, add an option for each new tool:

```typescript
{
  id: 'operation',
  type: 'dropdown',
  options: [
    // existing options...
    { label: 'New Action', id: 'new_action' },   // id maps to what tools.config.tool returns
  ],
}
```

### 3. Add subBlocks for new tool params

For each new tool, add subBlocks covering all its required params (and optional ones where useful). Apply `condition` to show them only for the right operation, and mark required params with `required`:

```typescript
// Required param for new_action
{
  id: 'someParam',
  title: 'Some Param',
  type: 'short-input',
  placeholder: 'e.g., value',
  condition: { field: 'operation', value: 'new_action' },
  required: { field: 'operation', value: 'new_action' },
},
// Optional param — put in advanced mode
{
  id: 'optionalParam',
  title: 'Optional Param',
  type: 'short-input',
  condition: { field: 'operation', value: 'new_action' },
  mode: 'advanced',
},
```

### 4. Update `tools.config.tool`

Ensure the tool selector returns the correct tool ID for every new operation. The simplest pattern:

```typescript
tool: (params) => `service_${params.operation}`,
// If operation dropdown IDs already match tool IDs, this requires no change.
```

If the dropdown IDs differ from tool IDs, add explicit mappings:

```typescript
tool: (params) => {
  const map: Record<string, string> = {
    new_action: 'service_new_action',
    // ...
  }
  return map[params.operation] ?? `service_${params.operation}`
},
```

### 5. Update `tools.config.params`

Add any type coercions needed for new params (runs at execution time, after variable resolution):

```typescript
params: (params) => {
  const result: Record<string, unknown> = {}
  if (params.limit != null && params.limit !== '') result.limit = Number(params.limit)
  if (params.newParamName) result.toolParamName = params.newParamName  // rename if IDs differ
  return result
},
```

### 6. Add new outputs

Add any new fields returned by the new tools to the block `outputs`:

```typescript
outputs: {
  // existing outputs...
  newField: { type: 'string', description: 'Description of new field' },
}
```

### 7. Add new inputs

Add new subBlock param IDs to the block `inputs` section:

```typescript
inputs: {
  // existing inputs...
  someParam: { type: 'string', description: 'Param description' },
  optionalParam: { type: 'string', description: 'Optional param description' },
}
```

### Block wiring checklist

- [ ] New tool IDs added to `tools.access`
- [ ] Operation dropdown has an option for each new tool
- [ ] SubBlocks cover all required params for each new tool
- [ ] SubBlocks have correct `condition` (only show for the right operation)
- [ ] Optional/rarely-used params set to `mode: 'advanced'`
- [ ] `tools.config.tool` returns correct ID for every new operation
- [ ] `tools.config.params` handles any ID remapping or type coercions
- [ ] New outputs added to block `outputs`
- [ ] New params added to block `inputs`

## V2 Tool Pattern

If creating V2 tools (API-aligned outputs), use `_v2` suffix:
- Tool ID: `{service}_{action}_v2`
- Variable name: `{action}V2Tool`
- Version: `'2.0.0'`
- Outputs: Flat, API-aligned (no content/metadata wrapper)

## Naming Convention

All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase for tool IDs.

## Checklist Before Finishing

- [ ] All tool IDs use snake_case
- [ ] Chose exactly one boundary: registered `InternalToolConfig.operation` or absolute external
      HTTP(S) `ToolConfig.request`
- [ ] No tool request points to `/api/...`, constructs a URL back to Sim, or declares
      `request.internal`
- [ ] No tool declares `directExecution`; in-process work uses a registered operation
- [ ] All params have explicit `required: true` or `required: false`
- [ ] All params have appropriate `visibility`
- [ ] All nullable response fields use `?? null`
- [ ] All optional outputs have `optional: true`
- [ ] No raw JSON dumps in outputs
- [ ] Types file has all interfaces
- [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
- [ ] Tools registered in `tools/registry.ts`
- [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed
- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's
      docs page is rendered from each tool's description, params, and outputs, and CI's
      `bun run docs:check` fails on stale pages
- [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
- [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms
      only where a concrete Sim `{{...}}` resolution path requires them
- [ ] Ordinary third-party inputs/results remain unchanged and private metadata never leaves Sim

## Final Validation (Required)

After creating all tools, you MUST validate every tool before finishing:

1. **Read every tool file** you created — do not skip any
2. **Cross-reference with the API docs** to verify:
   - All required params are marked `required: true`
   - All optional params are marked `required: false`
   - Param types match the API (string, number, boolean, json)
   - For external tools, request URL, method, headers, and body match the provider API spec
   - For internal tools, `operation.input` matches the handler schema and the handler is registered
     with no HTTP fallback
   - `transformResponse` extracts the correct fields from the API response
   - All output fields match what the API actually returns
   - No fields are missing from outputs that the API provides
   - No extra fields are defined in outputs that the API doesn't return
   - Every output field and JSON path is backed by docs or live-verified sample responses
3. **Verify consistency** across tools:
   - Shared types in `types.ts` match all tools that use them
   - Tool IDs in the barrel export match the tool file definitions
   - Error handling is consistent (error checks, meaningful messages)
4. **If any response schema is still unknown**, explicitly tell the user instead of guessing