Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

add-tools

Create tool configurations for a Sim integration by reading API docs

simstudioai · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add simstudioai/sim --skill add-tools

About this skill


name: add-tools description: Create tool configurations for a Sim integration by reading API docs argument-hint: [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 a directExecution property (it fails bun run check:tool-request-boundary), 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:

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, e.g. the 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

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 `_co

Read the complete source ↗