MCP Tools - Discovery, Schemas & Invocation

What Are MCP Tools?

Tools are functions that an MCP server exposes for AI models to call. Servers use tools to fetch data, run computations, modify state, or trigger side effects. Hosts discover available tools and decide how to present them to the model and user.

This page follows the core MCP 2025-11-25 specification. MCP Apps adds UI metadata to the normal tool definition but keeps the same discovery, invocation, result, and error model.

Declare the Tools Capability

A server that exposes tools declares the tools capability during initialization:

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

Set listChanged to true only when the server sends notifications/tools/list_changed after its available tools change. The client can then call tools/list again.

Discover Tools with `tools/list`

The client calls tools/list to discover the server’s tools. This operation supports opaque cursor pagination, so clients must continue while the response contains nextCursor.

{
  "method": "tools/list",
  "params": {
    "cursor": "opaque-cursor-from-the-previous-response"
  }
}

Each tool can declare:

Field	Required	Description
`name`	Yes	Case-sensitive identifier. MCP recommends 1 to 128 ASCII letters, digits, `_`, `-`, or `.`.
`title`	No	Human-readable display name.
`description`	No	What the tool does, written for the model and user.
`icons`	No	Display icons with source, MIME type, size, and theme hints.
`inputSchema`	Yes	JSON Schema for accepted arguments.
`outputSchema`	No	JSON Schema for returned `structuredContent`.
`annotations`	No	Untrusted behavior hints such as read-only or destructive.
`execution`	No	Execution metadata, including task support.

{
  "name": "get-weather",
  "title": "Get Weather",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name" }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperatureC": { "type": "number" },
      "summary": { "type": "string" }
    },
    "required": ["temperatureC", "summary"]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": true
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}

Validate Tool Input on the Server

Tools declare parameters with JSON Schema. When $schema is omitted, MCP uses JSON Schema 2020-12. inputSchema must be an object, including for tools with no parameters:

{
  "type": "object",
  "additionalProperties": false
}

The server MUST validate every tool input. A client may validate arguments before sending them, but the server cannot rely on that check because clients and models are outside the server’s trust boundary. Input that matches the JSON-RPC request shape but fails business validation should normally return a tool execution error with isError: true. A malformed tools/call request uses a JSON-RPC protocol error. TypeScript SDKs can accept schemas from libraries such as Zod and convert them to JSON Schema.

Invoke a Tool with `tools/call`

The client calls tools/call with the tool name and arguments. The server validates the arguments, checks authorization, executes the tool, and returns a result.

// Request
{ "method": "tools/call", "params": { "name": "get-weather", "arguments": { "location": "Tokyo" } } }

// Response
{ "content": [{ "type": "text", "text": "Tokyo: 22C, partly cloudy" }] }

Return Tool Results

Tool results commonly use these fields:

content: Content blocks such as text, images, audio, resource links, or embedded resources.
structuredContent: Optional JSON object for typed programmatic data. MCP Apps can pass it to the View.
isError: Marks a tool execution error.
_meta: Optional client or component metadata. Do not use it for facts the model must read.

When a tool returns structuredContent, MCP says it SHOULD also return serialized JSON in a text content block for backwards compatibility. If the tool declares outputSchema, the server MUST return structuredContent that conforms to it, and clients SHOULD validate the result. See Tool Results and Model Context for the MCP Apps split between content, structuredContent, and _meta.

Return Actionable Errors

MCP separates two error types:

Error type	Use it for	Shape
Protocol error	Unknown tool, malformed request, or server protocol failure.	JSON-RPC `error`.
Tool execution error	Invalid business input, upstream API failure, or tool logic failure.	Normal result with `isError: true`.

Tool execution errors should explain how the caller can fix the request because clients can pass that feedback to the model for a corrected retry.

Treat Annotations as Hints

Tools can include annotations that help hosts decide how to handle them. These hints do not replace authorization or user confirmation for sensitive actions.

Annotation	Description
`title`	Short human-readable tool title.
`readOnlyHint`	Tool does not modify state.
`destructiveHint`	Tool may perform destructive operations, such as deletes or overwrites.
`idempotentHint`	Calling the tool multiple times with the same arguments has the same effect.
`openWorldHint`	Tool interacts with external systems outside the server’s control.

Clients MUST treat annotations as untrusted unless they trust the server. Servers still need authentication, authorization, rate limits, input validation, and safe output handling.

Declare Task Support

The optional execution.taskSupport field tells clients whether a tool supports MCP task-augmented execution:

Value	Meaning
`"forbidden"`	The tool does not support task execution. This is the default.
`"optional"`	The caller may request task execution.
`"required"`	The caller must use task execution.

Task support belongs to the core MCP tool contract. It is separate from whether an MCP App tool renders a View.

registerAppTool

Tool and Resource Contract

See how MCP App tools, UI resources, and tool results fit together.

Tool Annotations

Use read-only, destructive, idempotent, and external-system hints in MCP App servers.

Core MCP Tools Specification

Read the normative tools protocol and security requirements.

In the sunpeak framework, tools are defined as individual files that are auto-discovered. See the Tool File Reference.

Overview

App

MCP

React

Server

Styling

Types

MCP Tools - Discovery, Schemas & Invocation

What Are MCP Tools?

Declare the Tools Capability

Discover Tools with `tools/list`

Validate Tool Input on the Server

Invoke a Tool with `tools/call`

Return Tool Results

Return Actionable Errors

Treat Annotations as Hints

Declare Task Support

registerAppTool

Tool and Resource Contract

Tool Annotations

Core MCP Tools Specification

​What Are MCP Tools?

​Declare the Tools Capability

​Discover Tools with tools/list

​Validate Tool Input on the Server

​Invoke a Tool with tools/call

​Return Tool Results

​Return Actionable Errors

​Treat Annotations as Hints

​Declare Task Support

​Related

registerAppTool

Tool and Resource Contract

Tool Annotations

Core MCP Tools Specification

What Are MCP Tools?

Declare the Tools Capability

Discover Tools with `tools/list`

Validate Tool Input on the Server

Invoke a Tool with `tools/call`

Return Tool Results

Return Actionable Errors

Treat Annotations as Hints

Declare Task Support

Related