Agent-driven workflows

The domain API (stitch.projects(), project.generate()) is the preferred interface for humans writing scripts. But if you’re building an AI agent, an automation pipeline, or need access to tools the domain layer doesn’t wrap yet, use the lower-level callTool and listTools APIs.

List available tools

Discover what the Stitch MCP server can do:

import { stitch } from "@google/stitch-sdk";

const { tools } = await stitch.listTools();
for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}

Call any tool by name

callTool gives you raw access to every MCP tool, including ones not yet surfaced in the domain API:

// Create a project
const result = await stitch.callTool("create_project", { title: "Agent Project" });
console.log(result);

// Generate a screen
const screen = await stitch.callTool("generate_screen_from_text", {
  projectId: result.name.replace("projects/", ""),
  prompt: "A dashboard with charts and KPIs",
});
console.log(screen);

How agents discover tool schemas

An agent calling callTool needs to know two things: what parameters a tool expects, and what the response looks like. The SDK provides two ways to get this information.

Runtime discovery with `listTools()`

Call listTools() to get the full catalog of tools with their JSON Schemas. An agent reads these schemas to understand what arguments to construct:

const { tools } = await stitch.listTools();
const createTool = tools.find(t => t.name === "create_project");
console.log(JSON.stringify(createTool.inputSchema, null, 2));
// → { type: "object", properties: { title: { type: "string", ... } } }

The agent can then construct a valid callTool invocation from the schema - no hardcoded knowledge of parameter names required.

Static schemas with `toolDefinitions`

The SDK also ships a generated toolDefinitions array (from tools-manifest.json) with the same schemas baked in at build time. This is what stitchTools() uses to wire tools into the Vercel AI SDK without a runtime listTools() call:

import { toolDefinitions } from "@google/stitch-sdk/tool-definitions"; // internal

for (const tool of toolDefinitions) {
  console.log(tool.name, Object.keys(tool.inputSchema.properties));
}

Responses are unstructured

callTool returns raw JSON from the MCP server - the shape depends on the tool. Agents should inspect the response dynamically rather than assuming a fixed structure. The domain API (project.generate(), screen.edit()) parses these responses into typed objects, but at the callTool level, it’s the agent’s job to interpret the result.

Mix domain and tool APIs

The stitch singleton exposes both layers through the same object. You can use callTool for creation, then switch to the domain API for everything else:

// Create via callTool (agent-style)
const raw = await stitch.callTool("create_project", { title: "Hybrid Flow" });

// Switch to domain API (human-style)
const project = stitch.project(raw.name);
const screen = await project.generate("A settings page");
const html = await screen.getHtml();

This is the identity map pattern - stitch.project(id) creates a Project handle from any project ID or resource name without an API call. Use it to bridge between raw tool results and the fluent domain API.

Build a custom client

If you need OAuth credentials or want to connect to a different Stitch environment, instantiate StitchToolClient directly:

import { StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({
  accessToken: process.env.STITCH_ACCESS_TOKEN,
  projectId: process.env.GOOGLE_CLOUD_PROJECT,
});

await client.connect();
const tools = await client.listTools();
console.log(`${tools.tools.length} tools available`);

await client.close();

When to use which

Pattern	Best for
Domain API (`stitch.projects()` → `project.generate()` → `screen.getHtml()`)	Human scripts, tutorials, straightforward workflows
`callTool`	AI agents, automation, tools not in the domain layer, dynamic tool selection
`stitchTools()`	Vercel AI SDK integration - see Use with AI SDK
Custom `StitchToolClient`	OAuth, multi-tenant, or non-default server environments