Tools

A tool is a typed action the model can call: hit an API, run a query, write a file. Each file in bot/tools/ defines one tool, and the filename becomes the tool name the model sees. Tools come in two execution flavors: server tools run on the serving host, and agent tools run as scripts where the agent runs. Every server tool can also be called directly, with no model turn.

Define a server tool

By default, execute runs in-process on the serving host with full access to process.env and your bot/lib/ code.

// bot/tools/inspect_pr.tsimport { defineTool } from "@cursor/bdk/tools";import { z } from "zod";export default defineTool({  description: "Inspect a pull request before approval.",  // execution: "server" is the default  inputSchema: z.object({ prUrl: z.string().url() }),  async execute({ prUrl }, ctx) {    return { prUrl, checks: ["unit", "lint"], ready: true };  },});

A tool definition needs a filename slug (the model-facing name), a description written for the model, an optional inputSchema, and the code that runs it. With a Zod inputSchema, the input is validated before execute runs and the input type is inferred. A plain JSON Schema object is forwarded as-is and the input arrives as raw JSON.

A server tool can call decide from @cursor/bdk/extensions/jev for a risk tier or a finding gate without a second model turn.

For multi-line descriptions, reminder prompts, and error messages, use prompt so the string can sit indented with the surrounding TypeScript:

import { prompt } from "@cursor/bdk";import { defineTool } from "@cursor/bdk/tools";import { z } from "zod";export default defineTool({  description: prompt`    Inspect a pull request before approval.    Prefer this over guessing from the title alone.  `,  inputSchema: z.object({ prUrl: z.string().url() }),  async execute({ prUrl }) {    return { prUrl };  },});

Tool context

execute receives a ctx with the runtime accessors:

ctx.host carries the shared host services: host.mcp (authored MCP connections: names(), listTools(name), callTool(name, tool, args)), host.github and host.slack (shared platform clients), host.kv and host.files (durable storage), host.otel (custom metrics and session tags; see OpenTelemetry), host.reminders (per-session wakes, when attached).

Return values

execute may return a string (passed to the model verbatim), a JSON-shaped value (serialized), or the envelope { content: [...], isError? } for rich results. Returns must be JSON-shaped: use object literals or type aliases. An interface type fails assignability (no index signature), and tsx won't catch it. Your typecheck will.

Throwing inside execute reports an error result to the model (isError: true). The turn and the server keep running.

Declare structured output

Set outputSchema when MCP clients need a structured result contract. Use a Zod schema or plain JSON Schema:

const Weather = z.object({  city: z.string(),  temperatureF: z.number(),});export default defineTool({  description: "Read the current weather.",  inputSchema: z.object({ city: z.string() }),  outputSchema: Weather,  async execute({ city }) {    return { city, temperatureF: 72 };  },});

BDK advertises the schema. It does not validate tool results against it. Plain object returns fill MCP structuredContent automatically. An envelope return must set structuredContent next to content and isError.

Use the exported ToolInput<TSchema> type when another function needs the input type inferred from a tool schema.

Control dry-run effects

Set effect to "read", "write", or a predicate over validated input. A dry-run session executes reads and answers writes without running their tool bodies. An authored tool without effect is treated as a write.

export default defineTool({  description: "Publish a release.",  inputSchema: z.object({ version: z.string() }),  effect: "write",  dryRunResult: ({ version }) => ({ published: false, version }),  async execute({ version }) {    return publishRelease(version);  },});

dryRunResult keeps the result shape stable. Without it, a stubbed write returns "Operation acknowledged.". Traces mark the result as stubbed.

Retry a transient read

When a read fails because the service or the network was briefly unavailable, BDK runs that call again before the model sees the error. A write, and a tool that does not declare an effect, runs once. An advertised MCP tool follows the same rule from its read-only annotation. Declaring effect: "read" opts the call into the default policy of 3 attempts.

If the read still fails, the tool error includes failed after 3 attempts. That tells the model to stop repeating the call.

Bound time arguments under asOf

Declare timeArgs with the input properties that carry time bounds. In a session created with asOf, every named argument must be an absolute ISO-8601 instant with a timezone, no later than the session's frozen instant. A call that omits one, or supplies a relative or later value, is refused with an error telling the model to retry with absolute bounds. Sessions without asOf ignore the declaration.

export default defineTool({  description: "Query telemetry between two instants.",  inputSchema: z.object({ since: z.string(), until: z.string() }),  effect: "read",  timeArgs: ["since", "until"],  async execute({ since, until }) {    return queryTelemetry(since, until);  },});

Every name in timeArgs must exist in the input schema; a session with asOf refuses to start otherwise, because a misspelled name would silently check nothing.

Define an agent tool

Set execution: "agent" and the tool materializes as a shell script that runs in the Cursor agent workspace. The script receives JSON arguments on stdin and prints its result on stdout. Use this flavor when the tool must run next to the checkout the agent works in.

import { defineTool } from "@cursor/bdk/tools";import { z } from "zod";export default defineTool({  description: "Echo a message from the agent workspace.",  execution: "agent",  inputSchema: z.object({ message: z.string() }),  script: `#!/usr/bin/env bashset -euo pipefailmessage=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["message"])')printf '%s\\n' "$message"`,});

Scripts land in the session workspace with a catalog in AGENTS.md.

Tools from an MCP connection, advertised by name

Set advertiseTools: true on a connection to expose its MCP tools by name. Add per-session auth when credentials depend on the caller. Model calls and direct tool calls use the same exposed names. See MCP connections for the full contract.

Call a tool without a model turn

Server tools can be called deterministically. You pick the tool and the input. Validation and execution match a model-initiated call, and no Cursor API key is needed.

Over HTTP, with the same auth chain as the session API:

curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \  -H 'content-type: application/json' \  -d '{"input":{"prUrl":"https://github.com/acme/checkout/pull/42"}}'# {"ok":true,"toolName":"inspect_pr","callId":"tool_inspect_pr_…",#  "isError":false,"result":{…},"durationMs":12}

From the CLI, which starts an ephemeral server unless --url targets a running one:

bdk call inspect_pr --dir . \  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'bdk call inspect_pr \  --url http://127.0.0.1:3000/<slug> \  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'

Programmatically, callTool(toolName, input, options?) is available on the serve handle, on channel route handlers and onStart args, and on schedule run handlers, so a channel can mix deterministic calls with model turns:

const outcome = await handle.callTool("inspect_pr", {  prUrl: "https://github.com/acme/checkout/pull/42",});if (outcome.isError) {  return outcome;}// { toolName, callId, isError, result, durationMs }

Omit both identifiers to run against an ephemeral workspace that is removed when the call returns. Pass sessionId (HTTP body, --session, or options.sessionId) or continuationToken (<channelId>:<key> as /v1/sessions lists it) to bind the call. The two are mutually exclusive.

Design habits

Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.

Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can't steer it.

Test tools with call before blaming prompts. If the tool's output is wrong, no instruction change fixes it.

Declare each tool's effect so dry-run sessions can execute reads and stub writes.

Related

• MCP connections: tools that come from MCP servers instead
• Extensions: tools installed as a package under a namespace
• Evals: gating tool decisions with calledTool