---
name: raycast-ai-extensions
description: "Build Raycast AI extensions — expose tools that Raycast AI can call to read and act on behalf of the user. Covers the tools[] manifest, tool function shape, AI instructions, confirmations for side-effecting tools, and evals. USE WHEN making an extension AI-callable or building tools for Raycast AI. Defer exact API to developers.raycast.com/ai."
cluster: raycast
version: 1.0.0
---

# Raycast AI Extensions

AI extensions let **Raycast AI** call your extension's **tools** to answer questions and take
actions ("@your-extension create an issue titled …"). You provide the tools; the model decides
when to call them. Build on `raycast-core` (manifest + command model); this spoke covers the AI
surface. Confirm current signatures at developers.raycast.com/ai.

## Mental model

- A **tool** is a typed function the AI may invoke: it receives validated input and returns data the model uses to continue. Tools are the AI analog of commands.
- Declare tools in **`package.json` → `tools[]`** (each with a `name`, `title`, and description the model reads to decide relevance), with a matching implementation file that default-exports the tool function.
- The extension's description and any **AI instructions** steer when/how the AI uses your tools — write them for the model, not the user.

## Designing good tools

- **One clear job per tool.** Prefer `getIssues` + `createIssue` over a mega-tool with a `mode` arg — the model routes better to focused tools.
- **Strong descriptions.** The tool/param descriptions are the model's only routing signal; say what it does, when to use it, and what each argument means.
- **Typed inputs.** Validate every argument; never trust the model's input blindly (same boundary discipline as user input).
- **Read vs write.** Mark/structure side-effecting tools so they require **confirmation** before mutating (create/delete/send). Read tools can run freely.

## Confirmations & safety

- Any tool that changes state, spends money, or sends something should request explicit user confirmation before executing (Raycast surfaces a confirmation UI).
- Return concise, structured results; don't dump secrets or huge payloads into the model context.

## Evals

- Raycast supports **evals** (in `package.json`) that assert the AI calls the right tool with the right args for representative prompts. Add evals for your core flows so model/prompt changes don't silently regress routing.

## Build & ship

- Develop with `ray develop` and test via the AI Chat / `@extension` mentions.
- Ships through the same Store flow → `raycast-store-publishing`.

## Guardrails

- Tool/param **descriptions are the routing brain** — invest in them.
- Validate inputs; gate every side-effecting tool behind confirmation.
- Keep tools small and single-purpose; cover them with evals.
- Never leak preference secrets into tool results or the model context.
- Verify exact `tools[]` schema, function signature, and eval format against developers.raycast.com/ai (this is the model, not a frozen API).