Skip to content
Swytchcode logo Swytchcode logo Swytchcode Docs docs

Manage Tools

Installing an integration makes its APIs available to your project, but it does not automatically allow your AI agent to use them.

Swytchcode uses a tool-based permission model. Before an AI agent can execute an API operation, the corresponding tool must be explicitly enabled in your project.

This gives you complete control over what your AI agent is allowed to do.

For example, you may want your agent to create GitHub issues and list pull requests, but never delete repositories. By only enabling the required tools, you define the execution surface of your project.

What is a tool?

A tool represents a single executable capability: an API method from one of your integrations.

Each tool has:

  • A unique canonical ID
  • Input parameters
  • Output schema
  • Authentication requirements
  • Documentation

Your AI agent discovers and executes tools instead of generating raw HTTP requests.

The tooling.json file

Every Swytchcode project contains a tooling.json file.

This file defines the tools that are available for execution inside your project.

Think of it as the project’s allow list.

If a tool is not present in tooling.json, it cannot be executed, even if the integration has been installed.

tooling.json


✓ github.pull_requests.list
✓ github.issues.create
✓ slack.messages.send


✗ github.repository.delete
✗ stripe.customer.delete

The CLI automatically updates this file as you add or remove tools.

In most cases, you won’t need to edit it manually.

Add tools

Use the add command to enable a tool.

Terminal window
swy add github.pull_requests.list

The CLI validates the tool, updates your project configuration, and makes it available for execution.

You can enable as many tools as your project requires.

Terminal window
swy add github.issues.create


swy add slack.messages.send


swy add stripe.customers.create

Only enabled tools become available to your AI agent.

swy add <canonical_id> is shorthand for swy add method <canonical_id> - the form used above. To enable a whole integration at once:

Terminal window
swy add method --all github   # enable every method from an integration at once

If an integration later publishes updates, swy sync will flag any enabled method whose definition has drifted so you know to re-run add and refresh it.

List enabled tools

To view every tool currently available in your project, use:

Terminal window
swy list

This displays all enabled methods.

Listing tools is useful when:

  • Verifying project configuration
  • Auditing available capabilities
  • Checking whether a tool has already been added

Discover tools

Sometimes you know what you want to accomplish, but not which tool to use.

The discover command searches installed integrations and returns relevant tools based on your intent.

For example:

Terminal window
swy discover "create a GitHub issue"

Instead of requiring you to remember exact tool names, Swytchcode helps you find the most appropriate match.

This is especially useful when working with large integrations that expose hundreds of methods.

Inspect a tool

Before executing a tool, you can inspect its documentation and schema.

Terminal window
swy info github.issues.create

The CLI displays useful information such as:

  • Description
  • Required inputs
  • Optional parameters
  • Authentication requirements
  • Expected response
  • Examples

Reviewing a tool before execution helps developers understand exactly what the API expects.

Understanding canonical IDs

Every tool has a unique identifier called a canonical ID.

Instead of referring to tools using natural language, Swytchcode uses canonical IDs to uniquely identify executable actions.

For example:

github.pull_requests.list


github.issues.create


stripe.customers.create


slack.messages.send

Canonical IDs are:

  • Unique
  • Stable
  • Predictable
  • Easy to reference in scripts and automation

Most CLI commands accept canonical IDs as input.

Methods

Each tool is a method: a single API operation.

Examples include:

  • Create an issue
  • Send a message
  • Create a customer
  • List repositories

Methods generally map to one API endpoint.

Typical tool workflow

Most developers follow the same process when working with tools.

Install Integration
        │
        ▼
Discover Tool
        │
        ▼
Inspect Tool
        │
        ▼
Add Tool
        │
        ▼
Execute Tool

As your project grows, you’ll continue adding new tools while keeping the execution surface limited to only what your application requires.

Best practices

Enable only the tools your project needs.

Related pages

Authentication

Connect your Swytchcode account and securely manage provider credentials.

Projects

Initialize and configure Swytchcode projects.

Integrations

Discover, install, and manage API integrations.

Execute Tools

Execute tools, pass inputs, and preview requests.

Policy Rules

Define custom rules to control when and how tools are allowed to execute.

Runtime SDK overview

JavaScript and Python SDKs for tool execution.

Smaller tool sets improve discoverability, reduce unnecessary context for AI agents, and make project permissions easier to audit.

Review tool documentation with the info command before enabling unfamiliar tools.

Use canonical IDs consistently when writing scripts, automation, or documentation.

Now that you’ve enabled the tools your AI agents can execute, it’s time to understand how Swytchcode executes them safely and reliably.

What's Next?

Execution Pipeline

Learn how every request is validated, authenticated, protected by policies, and executed.

Policy Rules

Define custom rules to control when and how tools are allowed to execute.

Retries

Learn how Swytchcode automatically retries transient failures for reliable execution.

Idempotency

Prevent duplicate operations when retrying mutating API requests.

manifest.json

Configure execution behavior, including retries, timeouts, concurrency, and idempotency.