Fetching tools and schemas

If you're building an agent, we recommend using sessions instead. See Tools and toolkits for how sessions discover and fetch tools automatically.

Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.

Basic usage

tools = devcaster.tools.get(
    user_id,
    toolkits=["GITHUB"]
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
const tools = await devcaster.tools.get(userId, {
  toolkits: ["GITHUB"]
});

Returns top 20 tools by default. Tools require a user_id because they're scoped to authenticated accounts. See User management and Authentication.

Tool schemas

Inspect tool parameters and types without a user_id:

tool = devcaster.tools.get_raw_devcaster_tool_by_slug("GMAIL_SEND_EMAIL")

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
// ---cut---
const tool = await devcaster.tools.getRawDevcasterToolBySlug("GMAIL_SEND_EMAIL");

Generate type-safe code for direct SDK execution with devcaster generate. This creates TypeScript or Python types from tool schemas.

View tool parameters and schemas visually in the Devcaster platform. Navigate to any toolkit and select a tool to see its input/output parameters.

Filtering tools

By toolkit

Get tools from specific apps. Returns top 20 tools by default.

# Fetch with limit for a specific user
tools = devcaster.tools.get(
    user_id,
    toolkits=["GITHUB"],
    limit=5  # Get top 5 tools
)

# Same filter but without user_id (for schemas)
raw_tools = devcaster.tools.get_raw_devcaster_tools(
    toolkits=["GITHUB"],
    limit=5
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Fetch with limit for a specific user
const limitedTools = await devcaster.tools.get(userId, {
  toolkits: ["GITHUB"],
  limit: 5  // Get top 5 tools
});

// Same filter but without userId (for schemas)
const rawTools = await devcaster.tools.getRawDevcasterTools({
  toolkits: ["GITHUB"],
  limit: 5
});

By name

Fetch specific tools when you know their names.

# Fetch specific tools by name
tools = devcaster.tools.get(
    user_id,
    tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
)

# Get schemas without user_id
raw_tools = devcaster.tools.get_raw_devcaster_tools(
    tools=["GITHUB_CREATE_ISSUE", "GITHUB_CREATE_PULL_REQUEST"]
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Fetch specific tools by name
const specificTools = await devcaster.tools.get(userId, {
  tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
});

// Get schemas without userId
const specificRawTools = await devcaster.tools.getRawDevcasterTools({
  tools: ["GITHUB_LIST_STARGAZERS", "GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER"]
});

By scopes

Filter OAuth tools by permission level. Only works with a single toolkit.

# Filter by OAuth scopes (single toolkit only)
tools = devcaster.tools.get(
    user_id,
    toolkits=["GITHUB"],
    scopes=["write:org"]
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Filter by OAuth scopes (single toolkit only)
const scopedTools = await devcaster.tools.get(userId, {
  toolkits: ["GITHUB"],
  scopes: ["write:org"]
});

By search (experimental)

Find tools semantically.

# Search tools semantically
tools = devcaster.tools.get(
    user_id,
    search="create calendar event"
)

# Search schemas without user_id
raw_tools = devcaster.tools.get_raw_devcaster_tools(
    search="create calendar event"
)

# Search within a specific toolkit
tools = devcaster.tools.get(
    user_id,
    search="issues",
    toolkits=["GITHUB"],
)

# Search toolkit schemas without user_id
raw_tools = devcaster.tools.get_raw_devcaster_tools(
    search="issues",
    toolkits=["GITHUB"]
)

import { Devcaster } from '@devcaster/core';
const devcaster = new Devcaster({ apiKey: 'your_api_key' });
const userId = 'user-123';
// ---cut---
// Search tools semantically
const searchResults = await devcaster.tools.get(userId, {
  search: "create google calendar event"
});

// Search schemas without userId
const searchRawTools = await devcaster.tools.getRawDevcasterTools({
  search: "create google calendar event"
});

// Search within a specific toolkit
const toolkitSearch = await devcaster.tools.get(userId, {
  search: "star a repository",
  toolkits: ["GITHUB"]
});

// Search toolkit schemas without userId
const toolkitSearchRaw = await devcaster.tools.getRawDevcasterTools({
  search: "star a repository",
  toolkits: ["GITHUB"]
});

Use specific toolkit versions in production to prevent breaking changes. See toolkit versioning.