Tools

Annotations & input examples

Behavioral hints for MCP clients and concrete inputExamples for complex tools.

Tool Annotations

Annotations are behavioral hints that tell MCP clients how a tool behaves. Clients can use them to decide when to prompt users for confirmation (human-in-the-loop).

server/mcp/tools/delete-user.ts

import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'delete-user',
  description: 'Delete a user account',
  inputSchema: {
    userId: z.string(),
  },
  annotations: {
    readOnlyHint: false,    // Tool modifies state
    destructiveHint: true,  // Tool performs destructive updates
    idempotentHint: true,   // Deleting the same user twice has no additional effect
    openWorldHint: false,   // Tool does not interact with external systems
  },
  handler: async ({ userId }) => {
    // ...
  },
})

Annotation Reference

Annotation	Type	Default	Description
`readOnlyHint`	`boolean`	`false`	If `true`, the tool only reads data without modifying any state (safe to retry).
`destructiveHint`	`boolean`	`true`	If `true`, the tool may perform destructive operations like deleting data. Only meaningful when `readOnlyHint` is `false`.
`idempotentHint`	`boolean`	`false`	If `true`, calling the tool multiple times with the same arguments has no additional effect beyond the first call. Only meaningful when `readOnlyHint` is `false`.
`openWorldHint`	`boolean`	`true`	If `true`, the tool may interact with the outside world (external APIs, internet). If `false`, it only operates on local/internal data.

Here are common annotation patterns for typical tools:

// Search, list, lookup, calculate...
annotations: {
  readOnlyHint: true,
  destructiveHint: false,
  openWorldHint: false,
}

// Creates a new record each time
annotations: {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: false,
  openWorldHint: false,
}

// Updates are idempotent (same input → same result)
annotations: {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: true,
  openWorldHint: false,
}

// Destructive and idempotent (deleting twice is the same)
annotations: {
  readOnlyHint: false,
  destructiveHint: true,
  idempotentHint: true,
  openWorldHint: false,
}

All annotations are hints — they are not guaranteed to be respected by every MCP client. Clients should never make security-critical decisions based on annotations from untrusted servers.

Input Examples

You can provide concrete usage examples for your tools using inputExamples. These examples are type-safe (matching your inputSchema) and are transmitted to clients via _meta.inputExamples.

Input examples help AI models understand how to correctly fill in tool parameters, especially for tools with optional fields or complex inputs.

server/mcp/tools/create-todo.ts

import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: 'Create a new todo',
  inputSchema: {
    title: z.string().describe('The title of the todo'),
    content: z.string().optional().describe('Optional description'),
  },
  inputExamples: [
    { title: 'Buy groceries', content: 'Milk, eggs, bread' },
    { title: 'Fix login bug' },  // content is optional
  ],
  handler: async ({ title, content }) => {
    // ...
  },
})

inputExamples are particularly useful for tools with optional parameters, enums, or complex nested inputs where showing concrete values helps models pick the right format.

Edit this pageorReport an issue

Schema, handler & returns

Define tool inputs and outputs with Zod, and return text, structured data, or media from handlers.

Errors & caching

H3 and plain errors in tool handlers, and Nitro-backed response caching.