> ## Documentation Index
> Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools — Discovery, Schemas & Invocation

> How MCP tools work: discovery via tools/list, input validation with JSON Schema, invocation via tools/call, and structured results.

## What Are MCP Tools?

Tools are functions that an [MCP server](/docs/mcp-apps/mcp/overview) 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.)                    |

```json theme={null}
{
  "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](https://json-schema.org/). The host validates arguments against the schema before invoking the tool. Schemas can also be defined with [Zod](https://zod.dev/) — 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.

```json theme={null}
// 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](/docs/mcp-apps/app/event-handlers#ontoolresult)).
* **`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.           |

## Related

<Card horizontal title="registerAppTool" icon="page" href="/docs/mcp-apps/server/register-app-tool">
  Register tools with UI metadata on the MCP server.
</Card>

<Card horizontal title="Tool and Resource Contract" icon="list-check" href="/docs/mcp-apps/server/tool-resource-contract">
  See how MCP App tools, UI resources, and tool results fit together.
</Card>

<Card horizontal title="Tool Annotations" icon="shield-check" href="/docs/mcp-apps/server/tool-annotations">
  Use read-only, destructive, idempotent, and external-system hints in MCP App servers.
</Card>

<Tip>
  In the [sunpeak framework](/docs/quickstart), tools are defined as individual files that are auto-discovered. See the [Tool File Reference](/docs/app-framework/tools/tool-file).
</Tip>