Skip to main content

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_answer for 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:

snippets/extend_server.py
"""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​

PartWhy it mattersIn the example
Clear descriptionThe 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 parameterBecomes 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 modelGives the tool an outputSchema and machine-readable structuredContent.Worksheet and WorksheetItem.
ToolAnnotationsTells 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 failuresReturns 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.