Tools, Resources, and Prompts: The Three Primitives

Introduction

Every MCP server, no matter how specialized, speaks the same three-word vocabulary. Master these three primitives and you can look at any server's documentation and immediately understand what it does and how to use it.

The three primitives are: Tools, Resources, and Prompts.

Core Concept

Tools: Actions the AI Can Take

A Tool is a callable function. When the AI decides a tool is relevant to your request, it invokes that tool with arguments and receives a result. The server does the actual work — the AI just decides when and how to call it.

Examples of Tools in the wild:

• web_search(query) — searches the web and returns results
• create_file(path, content) — writes a file to disk
• send_message(channel, text) — posts a message to a chat platform
• run_query(sql) — executes a database query

Knox's mcp-bridge MCP server — a bridge to the OpenClaw agent gateway — exposes exactly this pattern. It provides five tools to Claude Code, each prefixed openclaw_ after the gateway it talks to: openclaw_sessions_list, openclaw_sessions_history, openclaw_web_search, openclaw_system_event, and openclaw_gateway_health. Each is a discrete action. The AI calls whichever one fits the task.

The key point: tools can have side effects. Calling a tool might write to a database, send a network request, or delete a file. This is why the read/write distinction (covered in the “Read Tools vs Write Tools” lesson) matters so much.

Resources: Data the AI Can Read

A Resource is a data endpoint — something the AI can fetch and read. Resources are typically read-only. They're how the server surfaces structured data without the AI needing to "do" anything with it.

Examples of Resources:

• A list of open GitHub issues
• The contents of a configuration file
• A database row representing a customer
• A knowledge base article

Resources have URIs that identify them, similar to URLs. The AI (or the client on its behalf) fetches a resource and receives the content. No side effects, no writes — just data in.

Think of resources as the server's way of saying: "here is data you might need to reason about."

Prompts: Reusable Templates

Prompts are the least obvious primitive, but they're genuinely powerful once you understand them. A Prompt is a named, parameterized instruction template that the server exposes.

Instead of you typing the same complex instruction every time, the server packages it up as a reusable prompt. The client can list available prompts, select one, fill in parameters, and invoke it.

Examples of Prompts:

• summarize_document(doc_uri) — a template that tells the AI how to summarize a specific document format
• generate_commit_message(diff) — takes a git diff and returns a well-formatted commit message
• code_review(file_path, language) — a review template pre-filled with the server owner's preferred review criteria

Prompts are powerful for teams. A server can ship opinionated, consistent instruction templates that everyone on the team uses — no copy-pasting system prompts across sessions.

Practical Application

Here is how the three primitives look in a real server definition (simplified pseudocode based on MCP spec patterns):

# A minimal MCP server exposing all three primitives

# TOOL: an action with side effects
@server.tool("create_note")
def create_note(title: str, content: str) -> str:
    note_id = db.insert(title=title, content=content)
    return f"Created note {note_id}"

# RESOURCE: read-only data endpoint
@server.resource("notes://all")
def list_all_notes() -> list:
    return db.fetch_all_notes()

# RESOURCE: single item by ID
@server.resource("notes://{note_id}")
def get_note(note_id: str) -> dict:
    return db.fetch_note(note_id)

# PROMPT: reusable template
@server.prompt("summarize_notes")
def summarize_notes_prompt() -> str:
    return """
    Fetch all notes from the notes://all resource.
    Identify the top 3 recurring themes.
    Return a bullet-point summary organized by theme.
    """

When the AI client connects to this server, it discovers: one tool, two resources, one prompt. It now knows exactly what the server can do and how to use it.

Common Mistakes

Treating everything as a Tool. Beginners often reach for tools for everything, including data retrieval. If you only need to read data without side effects, model it as a . Resources are cheaper, safer, and more predictable.

Ignoring Prompts entirely. Prompts feel optional — and they are, technically — but they're where servers can encode expertise. If a server ships prompts, use them. They're usually better than improvising your own instructions.

Building a server before understanding what primitive fits your use case. If you're adding a "search my notes" capability: is that a Tool (AI calls a function) or a Resource (AI reads a URI)? Answer this before writing code. In this case it's probably a Tool if the search is dynamic, or a Resource if you're exposing a static index.

Summary

• MCP exposes three primitives: Tools (actions/verbs), Resources (data/nouns), Prompts (templates)
• Tools can have side effects; Resources are read-only; Prompts are reusable instruction packages
• Real servers mix all three — a knowledge server might have a search tool, a documents://all resource, and a summarize_document prompt
• Understanding these three primitives lets you read any MCP server's documentation and immediately understand its capabilities
• When building, choose the right primitive for the job — don't force everything into a Tool

What's Next

The next lesson puts this into practice. We walk through connecting your first real MCP server to an AI client, complete with an actual config file and a step-by-step walkthrough of what happens when the connection is established.