SDK ReferenceTypeScript SDK

Tools

Markdown

Usage

Access this class through the devcaster.tools property:

const devcaster = new Devcaster({ apiKey: 'your-api-key' });
const result = await devcaster.tools.list();

Methods

createCustomTool()

Creates a custom tool that can be used within the Devcaster SDK.

Custom tools allow you to extend the functionality of Devcaster with your own implementations while keeping a consistent interface for both built-in and custom tools.

async createCustomTool(body: CustomToolOptions<T>): Promise<...>

Parameters

NameTypeDescription
bodyCustomToolOptions<T>The configuration for the custom tool

Returns

Promise<...> — The created custom tool

Example

// creating a custom tool with a toolkit
await devcaster.tools.createCustomTool({
  name: 'My Custom Tool',
  description: 'A custom tool that does something specific',
  slug: 'MY_CUSTOM_TOOL',
  userId: 'default',
  connectedAccountId: '123',
  toolkitSlug: 'github',
  inputParameters: z.object({
    param1: z.string().describe('First parameter'),
  }),
  execute: async (input, connectionConfig, executeToolRequest) => {
    // Custom logic here
    return { data: { result: 'Success!' } };
  }
});
// creating a custom tool without a toolkit
await devcaster.tools.createCustomTool({
  name: 'My Custom Tool',
  description: 'A custom tool that does something specific',
  slug: 'MY_CUSTOM_TOOL',
  inputParameters: z.object({
    param1: z.string().describe('First parameter'),
  }),
  execute: async (input) => {
    // Custom logic here
    return { data: { result: 'Success!' } };
  }
});

execute()

Executes a given tool with the provided parameters.

This method calls the Devcaster API or a custom tool handler to execute the tool and returns the response. It automatically determines whether to use a custom tool or a Devcaster API tool based on the slug.

Version Control: By default, manual tool execution requires a specific toolkit version. If the version resolves to "latest", the execution will throw a DevcasterToolVersionRequiredError unless dangerouslySkipVersionCheck is set to true. This helps prevent unexpected behavior when new toolkit versions are released.

async execute(slug: string, body: object, modifiers?: ExecuteToolModifiers): Promise<...>

Parameters

NameTypeDescription
slugstringThe slug/ID of the tool to be executed
bodyobjectThe parameters to be passed to the tool
modifiers?ExecuteToolModifiersOptional modifiers to transform the request or response

Returns

Promise<...> — - The response from the tool execution

Example

const result = await devcaster.tools.execute('GITHUB_GET_REPOS', {
  userId: 'default',
  version: '20250909_00',
  arguments: { owner: 'devcaster' }
});
const result = await devcaster.tools.execute('HACKERNEWS_GET_USER', {
  userId: 'default',
  arguments: { userId: 'pg' },
  dangerouslySkipVersionCheck: true // Allows execution with "latest" version
});
// If toolkitVersions are set during Devcaster initialization, no need to pass version
const devcaster = new Devcaster({ toolkitVersions: { github: '20250909_00' } });
const result = await devcaster.tools.execute('GITHUB_GET_REPOS', {
  userId: 'default',
  arguments: { owner: 'devcaster' }
});
const result = await devcaster.tools.execute('GITHUB_GET_ISSUES', {
  userId: 'default',
  version: '20250909_00',
  arguments: { owner: 'devcaster', repo: 'sdk' }
}, {
  beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
    console.log(`Executing ${toolSlug} from ${toolkitSlug}`);
    return params;
  },
  afterExecute: ({ toolSlug, toolkitSlug, result }) => {
    console.log(`Completed ${toolSlug}`);
    return result;
  }
});

executeMetaTool()

Executes a devcaster meta tool based on tool router session

async executeMetaTool(toolSlug: string, body: { arguments?: Record<string, unknown>; sessionId: string }, modifiers?: SessionExecuteMetaModifiers): Promise<...>

Parameters

NameTypeDescription
toolSlugstringThe slug of the tool to execute
bodyobjectThe execution parameters
modifiers?SessionExecuteMetaModifiersThe modifiers to apply to the tool

Returns

Promise<...> — The response from the tool execution

get()

Get a list of tools from Devcaster based on filters. This method fetches the tools from the Devcaster API and wraps them using the provider.

Overload 1

async get(userId: string, filters: ToolListParams, options?: ProviderOptions): Promise<ReturnType>

Parameters

NameTypeDescription
userIdstringThe user id to get the tools for
filtersToolListParamsThe filters to apply when fetching tools
options?ProviderOptionsOptional provider options including modifiers

Returns

Promise<ReturnType> — The wrapped tools collection

Overload 2

async get(userId: string, slug: string, options?: ProviderOptions): Promise<ReturnType>

Parameters

NameTypeDescription
userIdstringThe user id to get the tool for
slugstringThe slug of the tool to fetch
options?ProviderOptionsOptional provider options including modifiers

Returns

Promise<ReturnType> — The wrapped tool

Example

// Get tools from the GitHub toolkit
const tools = await devcaster.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

// Get tools with search
const searchTools = await devcaster.tools.get('default', {
  search: 'user',
  limit: 10
});

// Get a specific tool by slug
const hackerNewsUserTool = await devcaster.tools.get('default', 'HACKERNEWS_GET_USER');

// Get a tool with schema modifications
const tool = await devcaster.tools.get('default', 'GITHUB_GET_REPOS', {
  modifySchema: (toolSlug, toolkitSlug, schema) => {
    // Customize the tool schema
    return {...schema, description: 'Custom description'};
  }
});

getInput()

Fetches the input parameters for a given tool.

This method is used to get the input parameters for a tool before executing it.

async getInput(slug: string, body: ToolGetInputParams): Promise<ToolGetInputResponse>

Parameters

NameTypeDescription
slugstringThe ID of the tool to find input for
bodyToolGetInputParamsThe parameters to be passed to the tool

Returns

Promise<ToolGetInputResponse> — The input parameters schema for the specified tool

Example

// Get input parameters for a specific tool
const inputParams = await devcaster.tools.getInput('GITHUB_CREATE_ISSUE', {
  userId: 'default'
});
console.log(inputParams.schema);

getRawDevcasterToolBySlug()

Retrieves a specific tool by its slug from the Devcaster API.

This method fetches a single tool in raw format without provider-specific wrapping, providing direct access to the tool's schema and metadata. Tool versions are controlled at the Devcaster SDK initialization level through the toolkitVersions configuration.

async getRawDevcasterToolBySlug(slug: string, options?: ToolRetrievalOptions): Promise<...>

Parameters

NameTypeDescription
slugstringThe unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
options?ToolRetrievalOptionsOptional configuration for tool retrieval

Returns

Promise<...> — The requested tool with its complete schema and metadata

Example

// Get a tool by slug
const tool = await devcaster.tools.getRawDevcasterToolBySlug('GITHUB_GET_REPOS');
console.log(tool.name, tool.description);

// Get a tool with schema transformation
const customizedTool = await devcaster.tools.getRawDevcasterToolBySlug(
  'SLACK_SEND_MESSAGE',
  {
    modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
      return {
        ...schema,
        description: `Enhanced ${schema.description} with custom modifications`,
        customMetadata: {
          lastModified: new Date().toISOString(),
          toolkit: toolkitSlug
        }
      };
    }
  }
);

// Get a custom tool (will check custom tools first)
const customTool = await devcaster.tools.getRawDevcasterToolBySlug('MY_CUSTOM_TOOL');

// Access tool properties
const githubTool = await devcaster.tools.getRawDevcasterToolBySlug('GITHUB_CREATE_ISSUE');
console.log({
  slug: githubTool.slug,
  name: githubTool.name,
  toolkit: githubTool.toolkit?.name,
  version: githubTool.version,
  availableVersions: githubTool.availableVersions,
  inputParameters: githubTool.inputParameters
});

getRawDevcasterTools()

Lists all tools available in the Devcaster SDK including custom tools.

This method fetches tools from the Devcaster API in raw format and combines them with any registered custom tools. The response can be filtered and modified as needed. It provides access to the underlying tool data without provider-specific wrapping.

async getRawDevcasterTools(query: ToolListParams, options?: SchemaModifierOptions): Promise<ToolList>

Parameters

NameTypeDescription
queryToolListParamsQuery parameters to filter the tools (required)
options?SchemaModifierOptionsOptional configuration for tool retrieval

Returns

Promise<ToolList> — List of tools matching the query criteria

Example

// Get tools from specific toolkits
const githubTools = await devcaster.tools.getRawDevcasterTools({
  toolkits: ['github'],
  limit: 10
});

// Get specific tools by slug
const specificTools = await devcaster.tools.getRawDevcasterTools({
  tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
});

// Get tools from specific toolkits
const githubTools = await devcaster.tools.getRawDevcasterTools({
  toolkits: ['github'],
  limit: 10
});

// Get tools with schema transformation
const customizedTools = await devcaster.tools.getRawDevcasterTools({
  toolkits: ['github'],
  limit: 5
}, {
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
    // Add custom properties to tool schema
    return {
      ...schema,
      customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
      tags: [...(schema.tags || []), 'customized']
    };
  }
});

// Search for tools
const searchResults = await devcaster.tools.getRawDevcasterTools({
  search: 'user management'
});

// Get tools by authentication config
const authSpecificTools = await devcaster.tools.getRawDevcasterTools({
  authConfigIds: ['auth_config_123']
});

getRawToolRouterMetaTools()

Fetches the meta tools for a tool router session. This method fetches the meta tools from the Devcaster API and transforms them to the expected format. It provides access to the underlying meta tool data without provider-specific wrapping.

async getRawToolRouterMetaTools(sessionId: string, options?: SchemaModifierOptions): Promise<ToolList>

Parameters

NameTypeDescription
sessionIdstring{string} The session id to get the meta tools for
options?SchemaModifierOptions{SchemaModifierOptions} Optional configuration for tool retrieval

Returns

Promise<ToolList> — The list of meta tools

Example

const metaTools = await devcaster.tools.getRawToolRouterMetaTools('session_123');
console.log(metaTools);

getToolsEnum()

Fetches the list of all available tools in the Devcaster SDK.

This method is mostly used by the CLI to get the list of tools. No filtering is done on the tools, the list is cached in the backend, no further optimization is required.

async getToolsEnum(): Promise<ToolRetrieveEnumResponse>

Returns

Promise<ToolRetrieveEnumResponse> — The complete list of all available tools with their metadata

Example

// Get all available tools as an enum
const toolsEnum = await devcaster.tools.getToolsEnum();
console.log(toolsEnum.items);

proxyExecute()

Proxies a custom request to a toolkit/integration.

This method allows sending custom requests to a specific toolkit or integration when you need more flexibility than the standard tool execution methods provide.

async proxyExecute(body: object): Promise<ToolProxyResponse>

Parameters

NameTypeDescription
bodyobjectThe parameters for the proxy request including toolkit slug and custom data

Returns

Promise<ToolProxyResponse> — The response from the proxied request

Example

// Send a custom request to a toolkit
const response = await devcaster.tools.proxyExecute({
  toolkitSlug: 'github',
  userId: 'default',
  data: {
    endpoint: '/repos/owner/repo/issues',
    method: 'GET'
  }
});
console.log(response.data);

On this page

UsageMethodscreateCustomTool()execute()executeMetaTool()get()getInput()getRawDevcasterToolBySlug()getRawDevcasterTools()getRawToolRouterMetaTools()getToolsEnum()proxyExecute()