Skip to main content

​
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:
FieldDescription
nameUnique identifier (e.g., "get-weather")
descriptionWhat the tool does, for the model to read
inputSchemaJSON Schema defining accepted parameters
annotationsHints 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"]
  }
}

​
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 contain two fields:
  • content — An array of content blocks (text, image, audio) that go into the model’s context. This is what the AI sees.
  • structuredContent — Optional typed data optimized for programmatic consumption. MCP Apps uses this to pass data to Views (see Event Handlers).

​
Annotations

Tools can include annotations that help hosts decide how to handle them:
AnnotationDescription
readOnlyHintTool does not modify state.
destructiveHintTool may perform destructive operations (deletes, overwrites).
idempotentHintCalling the tool multiple times with the same arguments has the same effect.
openWorldHintTool interacts with external systems outside the server’s control.

registerAppTool

Register tools with UI metadata on the MCP server.
In the sunpeak framework, tools are defined as individual files that are auto-discovered. See the Tool File Reference.