Generated by Answer me with HTML 0.5.5 · 2026-10-22 13:44 · ★ Star on GitHub

When Tools Get Called

read_document and edit_document run only when a client sends tools/call

sourcemcp_server.py

Lead: The server never calls its own tools. A client calls a tool when the model picks that tool to answer a request. Your project has no client yet: main.py only prints "Hello from mcp-docs!".

A

Who triggers a call

B

Which tool the model picks

User request	Tool the model calls	Python function
"Summarize plan.md"	read_doc_contents	read_document
"What is in spec.txt?"	read_doc_contents	read_document
"In plan.md, change 'steps' to 'phases'"	edit_document	edit_document
"Fix a typo in report.pdf"	read_doc_contents, then edit_document	both, in order
"What is MCP?"	tool	none

The model decides from the tool description and the parameter descriptions. A clear description makes the right pick more likely.

C

Name vs function

Clients call tools by the registered name: read_doc_contents.
read_document is only the Python function name. No client sees it.
edit_document uses the same name for both.

D

Ways to call them today

without writing a clientbash

# Open MCP Inspector; click Tools → Runuv run mcp dev mcp_server.py# Add the server to Claude Code, then ask about a documentclaude mcp add documents -- uv run mcp_server.py

Running the script alone does nothing visible

python mcp_server.py waits for JSON-RPC on stdin. No tool runs until a client sends tools/call.

---
title: When Tools Get Called
subtitle: read_document and edit_document run only when a client sends tools/call
source: mcp_server.py
---
Lead: The server never calls its own tools. A client calls a tool when the model picks that tool to answer a request. Your project has no client yet: `main.py` only prints "Hello from mcp-docs!".

## A Who triggers a call
```sequence num
User -> Host: "What does report.pdf say?"
Host -> Server: tools/list
Server --> Host: read_doc_contents, edit_document + schemas
Host -> Model: prompt + tool list
note Model: picks a tool by its name and description
Model --> Host: tool_use read_doc_contents {doc_id: "report.pdf"}
Host -> Server: tools/call read_doc_contents
note Server: runs read_document()
Server --> Host: "The report details ..."
Host -> Model: tool result
Model --> Host: final answer
Host --> User: answer
```

## B Which tool the model picks
| User request | Tool the model calls | Python function |
|---|---|---|
| "Summarize plan.md" | read_doc_contents | read_document |
| "What is in spec.txt?" | read_doc_contents | read_document |
| "In plan.md, change 'steps' to 'phases'" | edit_document | edit_document |
| "Fix a typo in report.pdf" | read_doc_contents, then edit_document | both, in order |
| "What is MCP?" | no tool | none |

The model decides from the tool `description` and the parameter descriptions. A clear description makes the right pick more likely.

## C Name vs function
- Clients call tools by the registered `name`: `read_doc_contents`.
- `read_document` is only the Python function name. No client sees it.
- `edit_document` uses the same name for both.

## D Ways to call them today
```bash title="without writing a client"
# Open MCP Inspector; click Tools → Run
uv run mcp dev mcp_server.py

# Add the server to Claude Code, then ask about a document
claude mcp add documents -- uv run mcp_server.py
```

```callout info Running the script alone does nothing visible
`python mcp_server.py` waits for JSON-RPC on stdin. No tool runs until a client sends `tools/call`.
```