MCP Tools — Discovery, Schemas & Invocation

What Are MCP Tools?

Tools are functions that an MCP server exposes for AI models to call. They’re the primary way servers provide actions — fetching data, running computations, modifying state, or triggering side effects. Hosts discover available tools when connecting and present them to the model as callable functions.

Discovery (`tools/list`)

When a client connects, the host calls tools/list to discover the server’s tools. Each tool declares:

Field	Description
`name`	Unique identifier (e.g., `"get-weather"`)
`description`	What the tool does, for the model to read
`inputSchema`	JSON Schema defining accepted parameters
`outputSchema`	Optional JSON Schema defining `structuredContent` returned by the tool
`annotations`	Hints about behavior (read-only, destructive, etc.)

{
  "name": "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"]
  }
}

Input Schemas

Tools declare their parameters using JSON Schema. The host validates arguments against the schema before invoking the tool. Schemas can also be defined with Zod — the SDK auto-converts them to JSON Schema.

Invocation (`tools/call`)

The host calls tools/call with the tool name and validated arguments. The server 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" }] }

Results

Tool results commonly use these fields:

content: An array of content blocks (text, image, audio, resource links, or embedded resources) that text-only clients and models can read.
structuredContent: Optional typed data optimized for programmatic consumption. MCP Apps uses this to pass model-visible data to Views (see Event Handlers).
isError: Optional flag for tool execution errors returned as a tool result.
_meta: Optional metadata for clients or components. Do not use it for facts the model must see.

When a tool returns structuredContent, MCP recommends also returning a serialized text block in content for compatibility. MCP Apps can then render structuredContent while text-only hosts still have usable output. Use _meta for component-only fields that the model should not see.

Annotations

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.

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.

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?

Discovery (`tools/list`)

Input Schemas

Invocation (`tools/call`)

Results

Annotations

registerAppTool

Tool and Resource Contract

Tool Annotations

​What Are MCP Tools?

​Discovery (tools/list)

​Input Schemas

​Invocation (tools/call)

​Results

​Annotations

​Related

registerAppTool

Tool and Resource Contract

Tool Annotations

What Are MCP Tools?

Discovery (`tools/list`)

Input Schemas

Invocation (`tools/call`)

Results

Annotations

Related