Add a new tool
This guide shows how to add a tool to the Edumaths360 Practice Server. The example adds make_worksheet, which returns several problems at once so a coaching teacher can hand out a timed practice set.
Before you start: you have cloned the repository and run uv sync --extra dev in server/. If MCP tools are new to you, do the first tutorial first.
1. Decide what the tool should and should not do
Write one sentence for each:
- Does: returns 1 to 10 problem statements on one topic, with their problem IDs.
- Does not: return answers. The student still uses
check_answerfor each problem. - Side effects: none. It is read-only and calling it twice with the same input gives the same result.
This decides the tool's description, its annotations and its tests.
2. Write the tool
The complete, tested example is in snippets/extend_server.py. It imports the existing server object and registers one more tool on it:
"""Example for the "Add a new tool" how-to guide.
Adds a make_worksheet tool to the Edumaths360 Practice Server without editing
the package, then runs the server over stdio.
Run it with: python snippets/extend_server.py
"""
import logging
import sys
from typing import Annotated
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations
from pydantic import BaseModel, Field
from edumaths360_mcp.problems import MAX_SEED, Difficulty, ProblemError, Topic, generate
from edumaths360_mcp.server import mcp
class WorksheetItem(BaseModel):
problem_id: str
statement: str
class Worksheet(BaseModel):
"""A set of problems to print or share. Answers are not included."""
title: str
items: list[WorksheetItem]
@mcp.tool(
title="Make a worksheet",
description=(
"Create a numbered set of practice problems on one topic. Returns statements and "
"problem IDs only, never answers. Use check_answer to mark each one."
),
annotations=ToolAnnotations(read_only_hint=True, idempotent_hint=True, open_world_hint=False),
)
def make_worksheet(
topic: Annotated[Topic, Field(description="Quant, reasoning or VARC topic to practise.")],
difficulty: Annotated[Difficulty, Field(description="How challenging the problems should be.")] = "easy",
count: Annotated[int, Field(ge=1, le=10, description="Number of problems, 1 to 10.")] = 5,
first_seed: Annotated[int, Field(ge=0, le=MAX_SEED - 10, description="Seed of the first problem.")] = 1,
) -> Worksheet:
try:
problems = [generate(topic, difficulty, first_seed + i) for i in range(count)]
except ProblemError as exc:
raise ToolError(str(exc)) from exc
return Worksheet(
title=f"{topic.replace('_', ' ').capitalize()} practice set ({difficulty})",
items=[WorksheetItem(problem_id=p.id, statement=p.statement) for p in problems],
)
if __name__ == "__main__":
logging.basicConfig(stream=sys.stderr, level=logging.INFO)
mcp.run(transport="stdio")
To make the tool part of the package instead, put the same function in server/src/edumaths360_mcp/server.py next to the other tools.
Checklist for every tool
| Part | Why it matters | In the example |
|---|---|---|
Clear description | The AI model reads it to decide when to call the tool. State what it returns and what it never returns. | "Returns statements and problem IDs only, never answers." |
Annotated[..., Field(...)] on every parameter | Becomes the JSON Schema. Limits are enforced before your code runs. | count is limited to 1–10, so one call cannot request a million problems. |
| A Pydantic return model | Gives the tool an outputSchema and machine-readable structuredContent. | Worksheet and WorksheetItem. |
ToolAnnotations | Tells the host whether the tool changes anything, so it can decide how much to ask the user. | read_only_hint=True, idempotent_hint=True. |
ToolError for expected failures | Returns a readable error with isError: true that the model can act on. | Raised if generating a problem fails, for example for an out-of-range seed. |
:::caution Annotations are hints, not security
A host may use read_only_hint to skip a confirmation prompt, but it cannot verify the claim. Only mark a tool read-only if it really is. See the security model.
:::
3. Try it with the Inspector
From the repository root:
npx @modelcontextprotocol/inspector --cli server/.venv/bin/python snippets/extend_server.py \
--method tools/call --tool-name make_worksheet \
--tool-arg topic=interest --tool-arg count=3
The structuredContent in the response contains the title Interest practice set (easy) and three items with IDs int-easy-1, int-easy-2 and int-easy-3.
4. Add tests
Test through a real MCP client, not by calling the Python function directly. That way the test also checks the schema, the validation and the error handling. The test for this example is in server/tests/test_snippets.py:
async with Client(server) as client:
names = [t.name for t in (await client.list_tools()).tools]
assert "make_worksheet" in names
result = await client.call_tool("make_worksheet", {"topic": "interest", "count": 3})
sheet = result.structured_content
assert sheet["title"] == "Interest practice set (easy)"
assert [i["problem_id"] for i in sheet["items"]] == ["int-easy-1", "int-easy-2", "int-easy-3"]
assert all(set(item) == {"problem_id", "statement"} for item in sheet["items"]) # no answers
bad = await client.call_tool("make_worksheet", {"topic": "interest", "count": 11})
assert bad.is_error
Run the suite:
cd server
uv run pytest -q
5. Document it
Add the tool to the tools reference with its input schema, output and errors, and open a pull request. The contributing guide lists the checks CI runs.