@vapi-ai/mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -1,96 +1,46 @@
 # Vapi MCP Server
 
-Build AI voice assistants and phone agents with [Vapi](https://vapi.ai) using the [Model Context Protocol](https://modelcontextprotocol.com/).
+Build AI voice assistants and phone agents with [Vapi](https://vapi.ai) from any agent or app that speaks the [Model Context Protocol](https://modelcontextprotocol.com/).
 
-## Setup
+## Connect to the hosted server
 
-The MCP server requires a Vapi API key. Get one from the [Vapi dashboard](https://dashboard.vapi.ai/org/api-keys).
+**You don't need to clone, install or run anything.** Vapi hosts this server for you:
 
-### Local Server (stdio)
+- **URL:** `https://mcp.vapi.ai/mcp` (Streamable HTTP)
+- **Header:** `Authorization: Bearer YOUR_VAPI_API_KEY`
 
-Configure any MCP client that supports local stdio servers to run:
+Get an API key from the [Vapi dashboard](https://dashboard.vapi.ai/org/api-keys).
 
-```text
-npx -y @vapi-ai/mcp-server
-```
+👉 **[Step-by-step setup for Codex, Claude Code, Cursor, VS Code, Hermes and Claude Desktop](https://docs.vapi.ai/sdk/mcp-server#connect-your-agent)**
 
-Set `VAPI_TOKEN` in the server environment. MCP client configuration formats vary, but the server definition generally looks like this:
+The two most common setups:
 
-```json
-{
-  "mcpServers": {
-    "vapi": {
-      "command": "npx",
-      "args": ["-y", "@vapi-ai/mcp-server"],
-      "env": {
-        "VAPI_TOKEN": "<your_vapi_token>"
-      }
-    }
-  }
-}
-```
-
-### Remote Server (Streamable HTTP)
-
-Clients that support remote MCP servers can connect directly:
-
-- URL: `https://mcp.vapi.ai/mcp`
-- Header: `Authorization: Bearer your_vapi_api_key_here`
-
-### Client-Specific Examples
-
-#### Claude Code
+**Claude Code**
 
 ```bash
-claude mcp add -e VAPI_TOKEN=your_vapi_token vapi -- npx -y @vapi-ai/mcp-server
-```
-
-#### Claude Desktop
-
-Use the local server configuration above in the Claude Desktop configuration file. To connect to the hosted server through an stdio bridge instead:
-
-```json
-{
-  "mcpServers": {
-    "vapi": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "https://mcp.vapi.ai/mcp",
-        "--header",
-        "Authorization: Bearer ${VAPI_TOKEN}"
-      ],
-      "env": {
-        "VAPI_TOKEN": "<your_vapi_token>"
-      }
-    }
-  }
-}
+export VAPI_API_KEY="YOUR_VAPI_API_KEY"
+claude mcp add --transport http --scope user vapi \
+  https://mcp.vapi.ai/mcp \
+  --header 'Authorization: Bearer ${VAPI_API_KEY}'
 ```
 
-### Optional Agent Skill
-
-The [`skill`](./skill) directory contains reusable instructions for AI coding agents that support Agent Skills. Install it using your host's skill installation process.
-
-For Claude Code:
+**Codex**
 
 ```bash
-mkdir -p ~/.claude/skills/vapi
-curl -o ~/.claude/skills/vapi/SKILL.md https://raw.githubusercontent.com/VapiAI/mcp-server/main/skill/SKILL.md
+export VAPI_API_KEY="YOUR_VAPI_API_KEY"
+codex mcp add vapi --url https://mcp.vapi.ai/mcp \
+  --bearer-token-env-var VAPI_API_KEY
 ```
 
----
-
-## Example Usage
-
-### Create a Voice Assistant
+Keep `VAPI_API_KEY` set whenever you launch your agent. Start a new session, then try:
 
-Ask your MCP-enabled agent:
 ```
-I want to build a voice assistant that can schedule appointments
+List my Vapi assistants.
 ```
 
-### Make an Outbound Call
+```
+I want to build a voice assistant that can schedule appointments.
+```
 
 ```
 Call +1234567890 using my appointment reminder assistant with these details:
@@ -99,25 +49,34 @@ Call +1234567890 using my appointment reminder assistant with these details:
 - Appointment time: 2:30 PM
 ```
 
-### Schedule a Future Call
-
 ```
 Schedule a call with my support assistant for next Tuesday at 3:00 PM to +1555123456
 ```
 
----
+> The legacy SSE endpoint (`https://mcp.vapi.ai/sse`) is deprecated. Move existing remote configurations to `https://mcp.vapi.ai/mcp`.
+
+### Optional: add the Vapi agent skill
+
+The [`skill`](./skill) directory contains reusable instructions for AI coding agents that support Agent Skills. Install it using your host's skill installation process.
 
-## Using Variable Values in Assistant Prompts
+For Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills/vapi
+curl -o ~/.claude/skills/vapi/SKILL.md https://raw.githubusercontent.com/VapiAI/mcp-server/main/skill/SKILL.md
+```
+
+### Using Variable Values in Assistant Prompts
 
 The `create_call` action supports passing dynamic variables through `assistantOverrides.variableValues`. Use double curly braces in your assistant's prompts: `{{variableName}}`.
 
-### Example Prompt with Variables
+#### Example Prompt with Variables
 
 ```
 Hello {{customerName}}, this is a reminder about your appointment on {{appointmentDate}} at {{appointmentTime}} with {{doctorName}}.
 ```
 
-### Default Variables
+#### Default Variables
 
 These are automatically available (no need to pass):
 
@@ -133,25 +92,59 @@ See [Vapi documentation](https://docs.vapi.ai/assistants/dynamic-variables#defau
 
 ---
 
-## Remote MCP Server
+## Oh, you're still here?
+
+You must want to [leave feedback](#leave-feedback), [run a local server yourself](#run-a-local-server) or [peek under the hood](#peek-under-the-hood). Read on.
 
-Connect to Vapi's hosted MCP server from any MCP client:
+### Leave feedback
 
-### Streamable HTTP (Recommended)
+- **Found a bug or want a tool we don't have?** [Open an issue](https://github.com/VapiAI/mcp-server/issues).
+- **Have a question or want to talk it through?** Join the [Vapi Discord](https://discord.gg/v5Ee6FhAZt).
+- **Want to fix it yourself?** Pull requests are welcome. See [Development](#development) for how to build and test.
 
-- URL: `https://mcp.vapi.ai/mcp`
-- Header: `Authorization: Bearer your_vapi_api_key_here`
+### Run a local server
 
-### SSE (Deprecated)
+Run the server on your own machine if your client only supports local stdio servers or you want to try unreleased changes. It uses the same tools as the hosted server.
 
-- URL: `https://mcp.vapi.ai/sse`
-- Header: `Authorization: Bearer your_vapi_api_key_here`
+Configure your MCP client to run:
+
+```text
+npx -y @vapi-ai/mcp-server
+```
+
+Set `VAPI_TOKEN` to your Vapi API key in the server environment. MCP client configuration formats vary, but the server definition generally looks like this:
+
+```json
+{
+  "mcpServers": {
+    "vapi": {
+      "command": "npx",
+      "args": ["-y", "@vapi-ai/mcp-server"],
+      "env": {
+        "VAPI_TOKEN": "<your_vapi_token>"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add -e VAPI_TOKEN=your_vapi_token vapi -- npx -y @vapi-ai/mcp-server
+```
+
+For Claude Desktop, add the configuration above to the Claude Desktop configuration file.
+
+To run a build from this repository instead, see [Local Development Config](#local-development-config).
 
 ---
 
-## Available Tools
+## Peek under the hood
+
+### Available Tools
 
-### Documentation
+#### Documentation
 | Tool | Description |
 |------|-------------|
 | `ask_vapi_docs` | Query the Fern docs MCP for current documentation passages and source URLs |
@@ -169,36 +162,36 @@ at startup. Discovery through `tools/list` makes no network requests; upstream
 failures are returned as tool errors. No extra MCP connection is needed. Do not
 include secrets or private customer data in docs questions.
 
-### Assistants
+#### Assistants
 | Tool | Description |
 |------|-------------|
-| `list_assistants` | List all assistants |
+| `list_assistants` | List assistants in pages of up to 10 |
 | `get_assistant` | Get assistant by ID |
 | `create_assistant` | Create new assistant |
 | `update_assistant` | Update assistant |
 
-### Calls
+#### Calls
 | Tool | Description |
 |------|-------------|
-| `list_calls` | List call history |
+| `list_calls` | List call history in pages of up to 10 |
 | `get_call` | Get call details |
 | `create_call` | Start outbound call (immediate or scheduled) |
 
-### Phone Numbers
+#### Phone Numbers
 | Tool | Description |
 |------|-------------|
-| `list_phone_numbers` | List phone numbers |
+| `list_phone_numbers` | List phone numbers in pages of up to 10 |
 | `get_phone_number` | Get phone number details |
 
-### Tools (Function Calling)
+#### Tools (Function Calling)
 | Tool | Description |
 |------|-------------|
-| `list_tools` | List custom tools |
+| `list_tools` | List custom tools in pages of up to 10 |
 | `get_tool` | Get tool details |
 | `create_tool` | Create tool for API integration |
 | `update_tool` | Update tool |
 
-### Public Skills
+#### Public Skills
 | Tool | Description |
 |------|-------------|
 | `search_skills` | Search public Vapi skills by keywords; omit `query` to browse |
@@ -224,7 +217,7 @@ calls and send no Vapi credentials upstream. The server still requires
 upstream failures are returned as tool errors. No GitHub token is needed for this
 public content. GitHub's unauthenticated API rate limits apply.
 
-### Simulations
+#### Simulations
 
 | Tool | Description |
 |------|-------------|
@@ -247,9 +240,7 @@ metadata in `itemsMetadata` and `itemsTruncated: true` when more items exist.
 Legacy array responses are also supported. Use `get_simulation_run_item` for
 the full details of a known item.
 
----
-
-## Development
+### Development
 
 ```bash
 # Install dependencies
@@ -262,7 +253,7 @@ npm run build
 npm run inspector
 ```
 
-### Local Development Config
+#### Local Development Config
 
 ```json
 {
@@ -278,7 +269,7 @@ npm run inspector
 }
 ```
 
-### Testing
+#### Testing
 
 ```bash
 # Safe default suite (build, mocked execution, contract, and stdio compatibility)
@@ -308,7 +299,7 @@ export VAPI_TOKEN=your_test_org_token_here
 npm run test:live:mutating
 ```
 
-### Input validation from OpenAPI
+#### Input validation from OpenAPI
 
 All 21 parameterized MCP tools use imported OpenAPI constraints through
 Zod's experimental `z.fromJSONSchema()`, pinned to Zod 4.6.7. This covers

package/dist/schemas/index.d.ts

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { VoiceInputSchema } from './assistant-openapi.js';
 export declare const EmptyInputSchema: z.ZodObject<{}, z.core.$strip>;
+export declare const ListInputSchema: z.ZodObject<{
+    before: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodISODateTime>>;
+}, z.core.$strict>;
 export declare const ModelProvider: {
     readonly OpenAI: "openai";
     readonly Anthropic: "anthropic";

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAwD,gBAAgB,EAAsH,MAAM,wBAAwB,CAAC;AAEpO,eAAO,MAAM,gBAAgB,gCAAe,CAAC;AAI7C,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAC/E,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAa/E,eAAO,MAAM,WAAW;;;CAGvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;AAE7E,eAAO,MAAM,aAAa;cACF,iBAAiB;;CAExC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;CAG/B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;CAMrB,CAAC;AAIX,eAAO,MAAM,kBAAkB;;;;iBAI7B,CAAC;AAIH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BrC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;iBAgBhC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwBrC,CAAC;AAIH,eAAO,MAAM,eAAe;;;;;;;;;;iBA4B1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAW3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAC;AAIH,eAAO,MAAM,yBAAyB;;iBAEpC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;iBAUlC,CAAC;AAIH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAC;AAqEH,eAAO,MAAM,qBAAqB;;;;;;;;;;kBAnEqB,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;kBAArF,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;iBAgFxI,CAAC;AAEL,eAAO,MAAM,qBAAqB;;;;;;;;;;kBAlFqB,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;kBAArF,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;iBAoF1I,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAQ3B,CAAC;AAIH,eAAO,MAAM,uBAAuB;;;iBAalC,CAAC;AAEH,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAwD,gBAAgB,EAAsH,MAAM,wBAAwB,CAAC;AAEpO,eAAO,MAAM,gBAAgB,gCAAe,CAAC;AAE7C,eAAO,MAAM,eAAe;;kBAK1B,CAAC;AAIH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAC/E,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAa/E,eAAO,MAAM,WAAW;;;CAGvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC,UAAU,CAAC,CAAC;AAE7E,eAAO,MAAM,aAAa;cACF,iBAAiB;;CAExC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;CAG/B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;CAMrB,CAAC;AAIX,eAAO,MAAM,kBAAkB;;;;iBAI7B,CAAC;AAIH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BrC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;iBAgBhC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwBrC,CAAC;AAIH,eAAO,MAAM,eAAe;;;;;;;;;;iBA4B1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAW3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAC;AAIH,eAAO,MAAM,yBAAyB;;iBAEpC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;iBAUlC,CAAC;AAIH,eAAO,MAAM,kBAAkB;;iBAE7B,CAAC;AAqEH,eAAO,MAAM,qBAAqB;;;;;;;;;;kBAnEqB,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;kBAArF,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;iBAgFxI,CAAC;AAEL,eAAO,MAAM,qBAAqB;;;;;;;;;;kBAlFqB,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;kBAArF,QAAQ;oBAAU,MAAM;wBAAc,MAAM;uBAAa,MAAM;0BAAgB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;iBAoF1I,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAQ3B,CAAC;AAIH,eAAO,MAAM,uBAAuB;;;iBAalC,CAAC;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/schemas/index.js

@@ -1,6 +1,10 @@
 import { z } from 'zod';
 import { CreateAssistantNameSchema, UpdateAssistantNameSchema, VoiceInputSchema, TranscriberInputSchema, LLMInputSchema, apiField, apiObjectField, requiredToolConfigurations, functionRequiresName } from './assistant-openapi.js';
 export const EmptyInputSchema = z.object({});
+export const ListInputSchema = z.strictObject({
+    // Keep discovery compact while validating the full ISO timestamp at runtime.
+    before: z.string().meta({ format: 'date-time' }).pipe(z.iso.datetime({ offset: true })).optional().describe('Use pagination.nextBefore to continue.'),
+});
 // ===== Model Provider and Models =====
 export const ModelProvider = {
     OpenAI: 'openai',

package/dist/tools/annotations.d.ts

@@ -0,0 +1,5 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+export declare const readOnly: (title: string, openWorldHint?: boolean) => ToolAnnotations;
+export declare const creates: (title: string, openWorldHint?: boolean) => ToolAnnotations;
+export declare const updates: (title: string) => ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/tools/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/tools/annotations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAO1E,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,EAAE,uBAAqB,KAAG,eAE9D,CAAC;AAEH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,EAAE,uBAAqB,KAAG,eAE7D,CAAC;AAGH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,eAEtC,CAAC"}

package/dist/tools/annotations.js

@@ -0,0 +1,14 @@
+// MCP tool annotations. Clients use these to label tools and decide when to ask
+// for confirmation, and directory review requires a title and readOnlyHint.
+// openWorldHint is false for calls into the Vapi API itself (a closed domain)
+// and true when a tool reaches outside it, such as dialing a phone number.
+export const readOnly = (title, openWorldHint = false) => ({
+    title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint,
+});
+export const creates = (title, openWorldHint = false) => ({
+    title, readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint,
+});
+// Updates overwrite fields on an existing resource, so clients should confirm them.
+export const updates = (title) => ({
+    title, readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false,
+});

package/dist/tools/api-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-schema.d.ts","sourceRoot":"","sources":["../../src/tools/api-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AAkElE,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,EACjB,YAAY,UAAU,SAuCvB,CAAC"}
+{"version":3,"file":"api-schema.d.ts","sourceRoot":"","sources":["../../src/tools/api-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAmB,MAAM,qBAAqB,CAAC;AAmElE,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,EACjB,YAAY,UAAU,SAwCvB,CAAC"}

package/dist/tools/api-schema.js

@@ -1,6 +1,7 @@
 import { VapiEnvironment } from '@vapi-ai/server-sdk';
 import { GetApiSchemaInputSchema } from '../schemas/index.js';
 import { createToolHandler } from './utils.js';
+import { readOnly } from './annotations.js';
 // The OpenAPI spec is about 2 MB, so load it once per client and keep only
 // its schemas. It is fetched through the client so it comes from the same
 // API environment the other tools call.
@@ -47,6 +48,7 @@ export const registerApiSchemaTools = (server, vapiClient) => {
             'References to other schemas are left as "#/components/schemas/<Name>" and listed in referencedSchemas, so look those up next if you need them. ' +
             'Use it to find fields that other tools accept through additionalFields.',
         inputSchema: GetApiSchemaInputSchema.shape,
+        annotations: readOnly('Get API Schema'),
     }, createToolHandler(async (data) => {
         const schemas = await loadSchemas(vapiClient);
         if (data.name) {

package/dist/tools/assistant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assistant.d.ts","sourceRoot":"","sources":["../../src/tools/assistant.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AAcvD,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,EACjB,YAAY,UAAU,SA4FvB,CAAC"}
+{"version":3,"file":"assistant.d.ts","sourceRoot":"","sources":["../../src/tools/assistant.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AAevD,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,EACjB,YAAY,UAAU,SA2FvB,CAAC"}

package/dist/tools/assistant.js

@@ -1,20 +1,19 @@
 import { registerValidatedTool } from './validation.js';
-import { EmptyInputSchema, CreateAssistantInputSchema, GetAssistantInputSchema, UpdateAssistantInputSchema, } from '../schemas/index.js';
+import { creates, readOnly, updates } from './annotations.js';
+import { ListInputSchema, CreateAssistantInputSchema, GetAssistantInputSchema, UpdateAssistantInputSchema, } from '../schemas/index.js';
 import { transformAssistantInput, transformAssistantOutput, transformUpdateAssistantInput, } from '../transformers/index.js';
 import { createToolHandler } from './utils.js';
+import { createV1ListHandler } from './list.js';
 export const registerAssistantTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_assistants', {
-        description: 'Lists all Vapi assistants',
-        inputSchema: EmptyInputSchema,
-    }, createToolHandler(async () => {
-        //   console.log('list_assistants');
-        const assistants = await vapiClient.assistants.list({ limit: 10 });
-        //   console.log('assistants', assistants);
-        return assistants.map(transformAssistantOutput);
-    }));
+        description: 'Lists up to 10 Vapi assistants',
+        inputSchema: ListInputSchema,
+        annotations: readOnly('List Assistants'),
+    }, createV1ListHandler(request => vapiClient.assistants.list(request), transformAssistantOutput));
     registerValidatedTool(server, 'create_assistant', {
         description: 'Creates a new Vapi assistant',
         inputSchema: CreateAssistantInputSchema,
+        annotations: creates('Create Assistant'),
     }, createToolHandler(async (data) => {
         //   console.log('create_assistant', data);
         const createAssistantDto = transformAssistantInput(data);
@@ -24,6 +23,7 @@ export const registerAssistantTools = (server, vapiClient) => {
     registerValidatedTool(server, 'get_assistant', {
         description: 'Gets a Vapi assistant by ID',
         inputSchema: GetAssistantInputSchema,
+        annotations: readOnly('Get Assistant'),
     }, createToolHandler(async (data) => {
         //   console.log('get_assistant', data);
         const assistantId = data.assistantId;
@@ -42,6 +42,7 @@ export const registerAssistantTools = (server, vapiClient) => {
     registerValidatedTool(server, 'update_assistant', {
         description: 'Updates an existing Vapi assistant',
         inputSchema: UpdateAssistantInputSchema,
+        annotations: updates('Update Assistant'),
     }, createToolHandler(async (data) => {
         const assistantId = data.assistantId;
         try {

package/dist/tools/call.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/tools/call.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AASvD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,EACjB,YAAY,UAAU,SAyCvB,CAAC"}
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/tools/call.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AAUvD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,EACjB,YAAY,UAAU,SAyCvB,CAAC"}

package/dist/tools/call.js

@@ -1,18 +1,19 @@
 import { registerValidatedTool } from './validation.js';
-import { EmptyInputSchema, CallInputSchema, GetCallInputSchema } from '../schemas/index.js';
+import { creates, readOnly } from './annotations.js';
+import { ListInputSchema, CallInputSchema, GetCallInputSchema } from '../schemas/index.js';
 import { transformCallInput, transformCallOutput, } from '../transformers/index.js';
 import { createToolHandler } from './utils.js';
+import { createV1ListHandler } from './list.js';
 export const registerCallTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_calls', {
-        description: 'Lists all Vapi calls',
-        inputSchema: EmptyInputSchema,
-    }, createToolHandler(async () => {
-        const calls = await vapiClient.calls.list({ limit: 10 });
-        return calls.map(transformCallOutput);
-    }));
+        description: 'Lists up to 10 Vapi calls',
+        inputSchema: ListInputSchema,
+        annotations: readOnly('List Calls'),
+    }, createV1ListHandler(request => vapiClient.calls.list(request), transformCallOutput));
     registerValidatedTool(server, 'create_call', {
         description: 'Creates a outbound call',
         inputSchema: CallInputSchema,
+        annotations: creates('Create Outbound Call', true),
     }, createToolHandler(async (data) => {
         const createCallDto = transformCallInput(data);
         const call = await vapiClient.calls.create(createCallDto);
@@ -21,6 +22,7 @@ export const registerCallTools = (server, vapiClient) => {
     registerValidatedTool(server, 'get_call', {
         description: 'Gets details of a specific call',
         inputSchema: GetCallInputSchema,
+        annotations: readOnly('Get Call'),
     }, createToolHandler(async (data) => {
         const call = await vapiClient.calls.get({ id: data.callId });
         return transformCallOutput(call);

package/dist/tools/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAazE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QAelD"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAczE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QAclD"}

package/dist/tools/docs.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { askVapiDocs } from '../knowledge/docs.js';
+import { readOnly } from './annotations.js';
 async function knowledgeResult(action) {
     try {
         return await action();
@@ -9,13 +10,12 @@ async function knowledgeResult(action) {
     }
 }
 export function registerDocsTools(server) {
-    const annotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
     server.registerTool('ask_vapi_docs', {
         description: 'Ask about current Vapi documentation through the Fern docs MCP. Returns relevant documentation passages and source URLs; use them to answer the question.',
         inputSchema: {
             question: z.string().trim().min(1).max(4000).describe('A specific question about Vapi configuration, APIs, SDKs or troubleshooting. Send no API keys or private customer data.'),
             topK: z.number().int().min(1).max(20).default(8).describe('Maximum number of relevant documentation passages.'),
-        }, annotations,
+        }, annotations: readOnly('Ask Vapi Docs', true),
     }, ({ question, topK }, extra) => knowledgeResult(async () => {
         const result = await askVapiDocs(question, topK, extra.signal);
         // The upstream SDK also types legacy toolResult responses. Fern uses the

package/dist/tools/list.d.ts

@@ -0,0 +1,34 @@
+export declare function v1ListPage<T extends {
+    createdAt: string;
+}>(rows: T[]): {
+    results: T[];
+    pagination: {
+        warning?: string | undefined;
+        pageSize: number;
+        hasMore: boolean;
+        nextBefore: string | null;
+    };
+};
+export declare function createV1ListHandler<T extends {
+    createdAt: string;
+}, R>(list: (request: {
+    limit: number;
+    createdAtLt?: string;
+}) => Promise<T[]>, transform: (row: T) => R): (data: {
+    before?: string;
+}) => Promise<import("./utils.js").ToolResponse | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        results: R[];
+        pagination: {
+            warning?: string | undefined;
+            pageSize: number;
+            hasMore: boolean;
+            nextBefore: string | null;
+        };
+    };
+}>;
+//# sourceMappingURL=list.d.ts.map

package/dist/tools/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/tools/list.ts"],"names":[],"mappings":"AAKA,wBAAgB,UAAU,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,CAAC,EAAE;;;;;;;;EAoBpE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,EACpE,IAAI,EAAE,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,EACxE,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAEV,MAAM;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;GAoBxC"}

package/dist/tools/list.js

@@ -0,0 +1,47 @@
+import { createErrorResponse, createSuccessResponse } from './utils.js';
+const PAGE_SIZE = 10;
+const TIE_WARNING = 'V1 cannot safely continue: more than 10 items share the same creation timestamp. No continuation is provided because it would skip items.';
+export function v1ListPage(rows) {
+    let end = Math.min(rows.length, PAGE_SIZE);
+    const hasMore = rows.length > PAGE_SIZE;
+    // V1 sorts only by creation time. Keep a timestamp group on the same page,
+    // using one bounded lookahead row to avoid skipping ties at the boundary.
+    if (hasMore) {
+        while (end > 0 && rows[end - 1].createdAt === rows[PAGE_SIZE].createdAt)
+            end--;
+    }
+    const blocked = hasMore && end === 0;
+    const results = rows.slice(0, blocked ? PAGE_SIZE : end);
+    return {
+        results,
+        pagination: {
+            pageSize: PAGE_SIZE,
+            hasMore,
+            nextBefore: hasMore && !blocked ? results[results.length - 1].createdAt : null,
+            ...(blocked ? { warning: TIE_WARNING } : {}),
+        },
+    };
+}
+export function createV1ListHandler(list, transform) {
+    return async (data) => {
+        try {
+            const page = v1ListPage(await list({
+                limit: PAGE_SIZE + 1,
+                ...(data.before ? { createdAtLt: data.before } : {}),
+            }));
+            const results = page.results.map(transform);
+            const response = createSuccessResponse(results);
+            return {
+                // Preserve the original array in the first text block for existing clients.
+                content: [...response.content, {
+                        type: 'text',
+                        text: JSON.stringify({ pagination: page.pagination }),
+                    }],
+                structuredContent: { results, pagination: page.pagination },
+            };
+        }
+        catch (error) {
+            return createErrorResponse(error);
+        }
+    };
+}

package/dist/tools/phone-number.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phone-number.d.ts","sourceRoot":"","sources":["../../src/tools/phone-number.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMjD,eAAO,MAAM,wBAAwB,GACnC,QAAQ,SAAS,EACjB,YAAY,UAAU,SA8BvB,CAAC"}
+{"version":3,"file":"phone-number.d.ts","sourceRoot":"","sources":["../../src/tools/phone-number.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAOjD,eAAO,MAAM,wBAAwB,GACnC,QAAQ,SAAS,EACjB,YAAY,UAAU,SA6BvB,CAAC"}

package/dist/tools/phone-number.js

@@ -1,18 +1,19 @@
 import { registerValidatedTool } from './validation.js';
+import { readOnly } from './annotations.js';
 import { transformPhoneNumberOutput } from '../transformers/index.js';
 import { createToolHandler } from './utils.js';
-import { EmptyInputSchema, GetPhoneNumberInputSchema } from '../schemas/index.js';
+import { ListInputSchema, GetPhoneNumberInputSchema } from '../schemas/index.js';
+import { createV1ListHandler } from './list.js';
 export const registerPhoneNumberTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_phone_numbers', {
-        description: 'Lists all Vapi phone numbers',
-        inputSchema: EmptyInputSchema,
-    }, createToolHandler(async () => {
-        const phoneNumbers = await vapiClient.phoneNumbers.list({ limit: 10 });
-        return phoneNumbers.map(transformPhoneNumberOutput);
-    }));
+        description: 'Lists up to 10 Vapi phone numbers',
+        inputSchema: ListInputSchema,
+        annotations: readOnly('List Phone Numbers'),
+    }, createV1ListHandler(request => vapiClient.phoneNumbers.list(request), transformPhoneNumberOutput));
     registerValidatedTool(server, 'get_phone_number', {
         description: 'Gets details of a specific phone number',
         inputSchema: GetPhoneNumberInputSchema,
+        annotations: readOnly('Get Phone Number'),
     }, createToolHandler(async (data) => {
         const phoneNumberId = data.phoneNumberId;
         const phoneNumber = await vapiClient.phoneNumbers.get({

package/dist/tools/simulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/tools/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AA2CvD,eAAO,MAAM,uBAAuB,GAClC,QAAQ,SAAS,EACjB,YAAY,UAAU,SA6NvB,CAAC"}
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/tools/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AA4CvD,eAAO,MAAM,uBAAuB,GAClC,QAAQ,SAAS,EACjB,YAAY,UAAU,SAyOvB,CAAC"}

package/dist/tools/simulation.js

@@ -1,5 +1,6 @@
 import { CreateSimulationInputSchema, CreateSimulationPersonalityInputSchema, CreateSimulationScenarioInputSchema, CreateSimulationSuiteInputSchema, GetSimulationRunInputSchema, GetSimulationRunItemInputSchema, ListSimulationResourcesInputSchema, ListSimulationRunsInputSchema, ListSimulationScenariosInputSchema, RunSimulationsInputSchema, } from '../schemas/index.js';
 import { registerValidatedTool } from './validation.js';
+import { creates, readOnly } from './annotations.js';
 import { createToolHandler } from './utils.js';
 const DEFAULT_LIMIT = 50;
 // Run items carry call snapshots and transcripts in these fields, which can
@@ -21,16 +22,19 @@ export const registerSimulationTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_simulation_personalities', {
         description: 'Lists simulation personalities: the simulated callers (testers) used in Vapi simulations',
         inputSchema: ListSimulationResourcesInputSchema,
+        annotations: readOnly('List Simulation Personalities'),
     }, createToolHandler(async (data) => vapiClient.simulationPersonalities.personalityControllerFindAll({
         limit: data.limit ?? DEFAULT_LIMIT,
     })));
     registerValidatedTool(server, 'create_simulation_personality', {
         description: 'Creates a simulation personality: the simulated caller that talks to the assistant under test',
         inputSchema: CreateSimulationPersonalityInputSchema,
+        annotations: creates('Create Simulation Personality'),
     }, createToolHandler(async (data) => vapiClient.simulationPersonalities.personalityControllerCreate(data)));
     registerValidatedTool(server, 'list_simulation_scenarios', {
         description: 'Lists simulation scenarios: the scripts testers follow and the checks that decide pass or fail',
         inputSchema: ListSimulationScenariosInputSchema,
+        annotations: readOnly('List Simulation Scenarios'),
     }, createToolHandler(async (data) => vapiClient.simulationScenarios.scenarioControllerFindAll({
         limit: data.limit ?? DEFAULT_LIMIT,
         ...(data.name && { name: data.name }),
@@ -38,6 +42,7 @@ export const registerSimulationTools = (server, vapiClient) => {
     registerValidatedTool(server, 'create_simulation_scenario', {
         description: 'Creates a simulation scenario: instructions for the tester plus evaluations that decide whether the assistant passed',
         inputSchema: CreateSimulationScenarioInputSchema,
+        annotations: creates('Create Simulation Scenario'),
     }, createToolHandler(async ({ additionalFields, ...data }) => vapiClient.simulationScenarios.scenarioControllerCreate({
         ...data,
         ...additionalFields,
@@ -45,22 +50,26 @@ export const registerSimulationTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_simulations', {
         description: 'Lists simulations. Each simulation pairs one scenario with one personality.',
         inputSchema: ListSimulationResourcesInputSchema,
+        annotations: readOnly('List Simulations'),
     }, createToolHandler(async (data) => vapiClient.simulations.simulationControllerFindAll({
         limit: data.limit ?? DEFAULT_LIMIT,
     })));
     registerValidatedTool(server, 'create_simulation', {
         description: 'Creates a simulation that pairs a scenario with a personality. Run it with run_simulations.',
         inputSchema: CreateSimulationInputSchema,
+        annotations: creates('Create Simulation'),
     }, createToolHandler(async (data) => vapiClient.simulations.simulationControllerCreate(data)));
     registerValidatedTool(server, 'list_simulation_suites', {
         description: 'Lists simulation suites: named groups of simulations',
         inputSchema: ListSimulationResourcesInputSchema,
+        annotations: readOnly('List Simulation Suites'),
     }, createToolHandler(async (data) => vapiClient.simulationSuites.simulationSuiteControllerFindAll({
         limit: data.limit ?? DEFAULT_LIMIT,
     })));
     registerValidatedTool(server, 'create_simulation_suite', {
         description: 'Creates a simulation suite that groups simulations so they can be run together',
         inputSchema: CreateSimulationSuiteInputSchema,
+        annotations: creates('Create Simulation Suite'),
     }, createToolHandler(async ({ additionalFields, ...data }) => vapiClient.simulationSuites.simulationSuiteControllerCreate({
         ...data,
         ...additionalFields,
@@ -69,6 +78,7 @@ export const registerSimulationTools = (server, vapiClient) => {
         description: 'Starts a simulation run of simulations and/or suites against an assistant or squad. ' +
             'Returns the run with its ID and a dashboard URL to share with the user. Check progress with get_simulation_run.',
         inputSchema: RunSimulationsInputSchema,
+        annotations: creates('Run Simulations'),
     }, createToolHandler(async (data) => {
         const simulations = [
             ...(data.simulationIds ?? []).map((simulationId) => ({
@@ -94,6 +104,7 @@ export const registerSimulationTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_simulation_runs', {
         description: 'Lists simulation runs, newest first',
         inputSchema: ListSimulationRunsInputSchema,
+        annotations: readOnly('List Simulation Runs'),
     }, createToolHandler(async (data) => vapiClient.simulationRuns.simulationRunControllerFindAll({
         limit: data.limit ?? DEFAULT_LIMIT,
         ...(data.status && { status: data.status }),
@@ -104,6 +115,7 @@ export const registerSimulationTools = (server, vapiClient) => {
             'itemsTruncated indicates omitted items; itemsMetadata preserves API pagination metadata. ' +
             'Use get_simulation_run_item for an item’s transcript and call details.',
         inputSchema: GetSimulationRunInputSchema,
+        annotations: readOnly('Get Simulation Run'),
     }, createToolHandler(async (data) => {
         const [run, response] = await Promise.all([
             vapiClient.simulationRuns.simulationRunControllerFindOne({
@@ -126,6 +138,7 @@ export const registerSimulationTools = (server, vapiClient) => {
     registerValidatedTool(server, 'get_simulation_run_item', {
         description: 'Gets one simulation run item in full, including results, call snapshots, transcript, and improvement suggestions',
         inputSchema: GetSimulationRunItemInputSchema,
+        annotations: readOnly('Get Simulation Run Item'),
     }, createToolHandler(async (data) => vapiClient.simulationRuns.simulationRunControllerFindItem({
         id: data.runId,
         itemId: data.itemId,

package/dist/tools/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/tools/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiBzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QAkBnD"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/tools/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkBzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QAiBnD"}

package/dist/tools/skills.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { PublicSkills } from '../knowledge/skills.js';
+import { readOnly } from './annotations.js';
 async function knowledgeResult(action) {
     try {
         return await action();
@@ -13,19 +14,18 @@ function jsonResult(data) {
 }
 export function registerSkillTools(server) {
     const skills = new PublicSkills();
-    const annotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
     server.registerTool('search_skills', {
         description: 'Find Vapi agent skills in the public VapiAI/skills repository by name, description or content. Omit query to browse. Use load_skill to read a result.',
         inputSchema: {
             query: z.string().trim().max(500).default('').describe('Keywords describing the Vapi task, or empty to browse all skills.'),
             limit: z.number().int().min(1).max(30).default(10),
-        }, annotations,
+        }, annotations: readOnly('Search Vapi Skills', true),
     }, ({ query, limit }) => knowledgeResult(async () => jsonResult(await skills.search(query, limit))));
     server.registerTool('load_skill', {
         description: 'Read a public Vapi skill or one of its supporting files. Start with SKILL.md, then load relevant files from the returned file list as needed. Returns instructions for this task; does not install skills or execute scripts.',
         inputSchema: {
             name: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).max(100).describe('Exact skill name from search_skills.'),
             path: z.string().min(1).max(300).default('SKILL.md').describe('File path relative to the skill directory, such as SKILL.md or references/hooks.md.'),
-        }, annotations,
+        }, annotations: readOnly('Load Vapi Skill', true),
     }, ({ name, path }) => knowledgeResult(async () => jsonResult(await skills.load(name, path))));
 }

package/dist/tools/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tools/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AAMvD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,EACjB,YAAY,UAAU,SA2DvB,CAAC"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tools/tool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAQ,MAAM,qBAAqB,CAAC;AAOvD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,EACjB,YAAY,UAAU,SA4DvB,CAAC"}

package/dist/tools/tool.js

@@ -1,18 +1,19 @@
 import { registerValidatedTool } from './validation.js';
-import { EmptyInputSchema, GetToolInputSchema, CreateToolInputSchema, UpdateToolInputSchema } from '../schemas/index.js';
+import { creates, readOnly, updates } from './annotations.js';
+import { ListInputSchema, GetToolInputSchema, CreateToolInputSchema, UpdateToolInputSchema } from '../schemas/index.js';
 import { transformToolInput, transformUpdateToolInput, transformToolOutput } from '../transformers/index.js';
 import { createToolHandler } from './utils.js';
+import { createV1ListHandler } from './list.js';
 export const registerToolTools = (server, vapiClient) => {
     registerValidatedTool(server, 'list_tools', {
-        description: 'Lists all Vapi tools',
-        inputSchema: EmptyInputSchema,
-    }, createToolHandler(async () => {
-        const tools = await vapiClient.tools.list({ limit: 10 });
-        return tools.map(transformToolOutput);
-    }));
+        description: 'Lists up to 10 Vapi tools',
+        inputSchema: ListInputSchema,
+        annotations: readOnly('List Tools'),
+    }, createV1ListHandler(request => vapiClient.tools.list(request), transformToolOutput));
     registerValidatedTool(server, 'get_tool', {
         description: 'Gets details of a specific tool',
         inputSchema: GetToolInputSchema,
+        annotations: readOnly('Get Tool'),
     }, createToolHandler(async (data) => {
         const tool = await vapiClient.tools.get({ id: data.toolId });
         return transformToolOutput(tool);
@@ -20,6 +21,7 @@ export const registerToolTools = (server, vapiClient) => {
     registerValidatedTool(server, 'create_tool', {
         description: 'Creates a new Vapi tool',
         inputSchema: CreateToolInputSchema,
+        annotations: creates('Create Tool'),
     }, createToolHandler(async (data) => {
         const createToolDto = transformToolInput(data);
         const tool = await vapiClient.tools.create(createToolDto);
@@ -28,6 +30,7 @@ export const registerToolTools = (server, vapiClient) => {
     registerValidatedTool(server, 'update_tool', {
         description: 'Updates an existing Vapi tool',
         inputSchema: UpdateToolInputSchema,
+        annotations: updates('Update Tool'),
     }, createToolHandler(async (data) => {
         const existingTool = await vapiClient.tools.get({ id: data.toolId });
         const updateToolDto = transformUpdateToolInput(data, existingTool);

package/dist/tools/validation.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import type { ToolResponse } from './utils.js';
 type Issue = z.core.$ZodIssue;
@@ -17,6 +18,7 @@ export declare function validationIssues(issues: Issue[], input: unknown, prefix
 export declare function registerValidatedTool<Schema extends z.ZodType>(server: McpServer, name: string, config: {
     description: string;
     inputSchema: Schema;
+    annotations: ToolAnnotations;
 }, handler: (params: z.output<Schema>) => Promise<ToolResponse>): import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredTool;
 export {};
 //# sourceMappingURL=validation.d.ts.map

package/dist/tools/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/tools/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,KAAK,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;AAC9B,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IACvE,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACxE,CAAC;AAcF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAE,WAAW,EAAO,GAAG,UAAU,EAAE,CA8C1G;AAWD,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EAC5D,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACpD,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,oEAsB7D"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/tools/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,KAAK,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;AAC9B,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;IACvE,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACxE,CAAC;AAcF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAE,WAAW,EAAO,GAAG,UAAU,EAAE,CA8C1G;AAWD,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EAC5D,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,eAAe,CAAA;CAAE,EAClF,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,oEAsB7D"}

package/dist/tools/validation.js

@@ -78,7 +78,7 @@ export function registerValidatedTool(server, name, config, handler) {
     // boundary lets us format validation failures before the SDK stringifies a
     // raw ZodError. No request reaches the API handler before parsing succeeds.
     const transportSchema = z.object({}).passthrough().meta(summarizeInputSchema(z.toJSONSchema(schema, { io: 'input', target: 'draft-07' })));
-    return server.registerTool(name, { description: config.description, inputSchema: transportSchema }, async (raw) => {
+    return server.registerTool(name, { description: config.description, inputSchema: transportSchema, annotations: config.annotations }, async (raw) => {
         const parsed = await schema.safeParseAsync(raw);
         if (!parsed.success) {
             const all = validationIssues(parsed.error.issues, raw);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vapi-ai/mcp-server",
   "description": "Build AI voice assistants and phone agents with Vapi through the Model Context Protocol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",