Tools

Tools

Expose Python functions as executable capabilities for your MCP clients.

Tools are the core primitives that let an LLM reach outside its training data: query a database, hit an API, crunch numbers, or open a file. In Hyperia, a tool is just a Python function decorated with @mcp.tool() and surfaced through the Model Context Protocol.

What are Tools?

When an LLM decides to call a tool:

  1. It sends a request containing parameters that match the tool’s input schema.

  2. Hyperia validates those parameters against your function signature (types, constraints, defaults).

  3. Your function executes with the validated inputs.

  4. The result is returned to the LLM, which can use it to craft its next response.

That single loop enables powerful behaviours—calculations, searches, side‑effects—well beyond what the model “knows” natively.

The @tool Decorator

Creating a tool is as simple as decorating a function:

from hyperia import Hyperia

mcp = Hyperia(name="CalculatorServer")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Adds two numbers."""
    return a + b

When registered, Hyperia automatically:

  • Uses the function name (add) as the tool name.

  • Uses the docstring as the description.

  • Generates a JSON input schema from type hints.

  • Handles validation and error reporting.

Note Variadic signatures (*args, **kwargs) are not supported—Hyperia must know every parameter to build a complete schema.

Parameter Basics

Type Annotations

Type hints are required for robust schemas and validation.

@mcp.tool()
def analyze_text(
    text: str,
    max_tokens: int = 100,
    language: str | None = None,
) -> dict:
    """Analyse the provided text."""
    ...

Rich Metadata with Annotated + Field

Use Annotated to attach Pydantic Field metadata—descriptions, ranges, regex, etc.—without polluting the default value column:

from typing import Annotated, Literal
from pydantic import Field

@mcp.tool()
def process_image(
    image_url: Annotated[str, Field(description="URL of the image to process")],
    resize: Annotated[bool, Field(description="Whether to resize the image")] = False,
    width: Annotated[int, Field(description="Target width", ge=1, le=2000)] = 800,
    fmt: Annotated[Literal["jpeg", "png", "webp"], Field(description="Output format")] = "jpeg",
) -> dict:
    """Process an image with optional resizing."""

You can embed Field as the default value, but Annotated keeps type hints clear:

@mcp.tool()
def search_db(
    query: str = Field(description="Search query"),
    limit: int = Field(10, description="Max results", ge=1, le=100),
) -> list:
    ...

Supported Types

Hyperia supports nearly every Pydantic‑compatible type. A non‑exhaustive list:

Category
Examples
Notes

Basic scalars

int, float, str, bool

—

Binary

bytes

Raw bytes (Base64 handled manually)

Date/Time

datetime, date, timedelta

ISO‑8601 strings auto‑parsed

Collections

list[int], dict[str, float], set[str], tuple[int, int]

Nested combos allowed

Optional / Union

`int

None, str

Constrained

Literal["A", "B"], Enum

Value whitelists

Paths

Path

Auto‑converted from str

UUIDs

UUID

Auto‑converted

Pydantic models

User

Full validation & nested schemas

See Parameter Types below for deep dives and examples.

Optional Arguments

Standard Python rules apply: parameters without defaults are required; those with defaults (or | None) are optional.

@mcp.tool()
def search_products(
    query: str,
    max_results: int = 10,
    sort_by: str = "relevance",
    category: str | None = None,
) -> list[dict]:
    ...

Advanced Decorator Metadata

Override auto‑inferred values or add tags:

@mcp.tool(
    name="find_products",
    description="Search the product catalogue with optional filtering.",
    tags={"catalogue", "search"},
)
def _search_impl(query: str, category: str | None = None) -> list[dict]:
    ...

  • name – Explicit tool identifier exposed via MCP.

  • description – Overrides docstring for LLM visibility.

  • tags – Arbitrary strings clients may use for grouping or filtering.

Async vs Sync Tools

Hyperia is fully async‑aware:

# CPU‑bound / quick
@mcp.tool()
def distance(a: float, b: float) -> float:
    ...

# I/O‑bound
@mcp.tool()
async def fetch_weather(city: str) -> dict:
    async with aiohttp.ClientSession() as s:
        async with s.get(f"https://api.weather/{city}") as resp:
            resp.raise_for_status()
            return await resp.json()

Use async def whenever your tool performs blocking I/O (HTTP, DB, file access) to keep the event loop responsive.

Return Values

Hyperia serialises return values automatically:

Return Type
MCP Content

str

TextContent

dict, list, BaseModel

JSON‑serialised TextContent

bytes

Base64‑encoded BlobResourceContents

hyperia.Image helper

ImageContent

None

No content

Other types are coerced to str if possible.

from hyperia import Hyperia, Image
import io
from PIL import Image as PILImage

mcp = Hyperia("ImageDemo")

@mcp.tool()
def solid_png(width: int, height: int, colour: str) -> Image:
    img = PILImage.new("RGB", (width, height), colour)
    buf = io.BytesIO()
    img.save(buf, format="PNG")
    return Image(data=buf.getvalue(), format="png")

Error Handling

If a tool fails, raise any Python exception or hyperia.ToolError.

  • Standard exceptions → logged; generic error sent to client.

  • ToolError → message forwarded, letting the LLM reason about the cause.

from hyperia import Hyperia, ToolError

mcp = Hyperia("DivideDemo")

@mcp.tool()
def divide(a: float, b: float) -> float:
    if b == 0:
        raise ToolError("Division by zero is not allowed.")
    return a / b

Tool Annotations

Add advisory metadata (does not consume LLM tokens) via annotations=:

@mcp.tool(
    annotations={
        "title": "Calculate Sum",
        "readOnlyHint": True,
        "openWorldHint": False,
    }
)
def calc_sum(a: int, b: int) -> int:
    return a + b
Annotation
Type
Default
Purpose

title

string

—

UI‑friendly label

readOnlyHint

bool

False

Indicates no state change

destructiveHint

bool

True

If changes are irreversible

idempotentHint

bool

False

Repeat calls ⇒ same effect

openWorldHint

bool

True

Touches external systems

Accessing MCP Context

Inject a Context‑typed param to tap logging, resources, sampling, progress, etc.

from hyperia import Hyperia, Context

mcp = Hyperia("ContextDemo")

@mcp.tool()
async def process_data(uri: str, ctx: Context) -> dict:
    await ctx.info(f"Processing {uri}")
    res = await ctx.read_resource(uri)
    data = res[0].content if res else ""
    await ctx.report_progress(50, 100)
    summary = await ctx.sample(f"Summarise: {data[:200]}")
    await ctx.report_progress(100, 100)
    return {"length": len(data), "summary": summary.text}

See the Context chapter for the full API.

Server Behaviour Controls

Duplicate Tool Names

Configure via on_duplicate_tools= at server creation:

mcp = Hyperia(name="StrictServer", on_duplicate_tools="error")

Options: "warn" (default), "error", "replace", "ignore".

Removing Tools Dynamically

mcp.remove_tool("calculate_sum")

Legacy JSON Parsing

Set HYPERIA_TOOL_ATTEMPT_PARSE_JSON_ARGS=1 to re‑enable old behaviour that auto‑parsed stringified JSON args. Default is off for strict validation.

Deep‑Dive: Parameter Types

Hyperia leans on Pydantic for validation and coercion. Highlights below—see linked sections for more.

Built‑in Scalars

@mcp.tool()
def process_values(name: str, count: int, amount: float, enabled: bool):
    ...

Strings like "42" are coerced to int where appropriate.

Date & Time

from datetime import datetime, date, timedelta

@mcp.tool()
def schedule(event_date: date, event_time: datetime, duration: timedelta = timedelta(hours=1)):
    ...

Collections

@mcp.tool()
def analyse(values: list[float], props: dict[str, str], ids: set[int]):
    ...

Union / Optional

@mcp.tool()
def flexible(query: str | int, filters: dict | None = None):
    ...

Constrained Literals & Enums

from typing import Literal

@mcp.tool()
def sort(data: list[float], order: Literal["asc", "desc"] = "asc"):
    ...
from enum import Enum
class Colour(Enum):
    RED = "red"
    GREEN = "green"

@mcp.tool()
def filter_colour(img: bytes, colour: Colour = Colour.RED):
    ...

Binary Data

Raw bytes or base64 strings (decoded manually):

@mcp.tool()
def process_binary(data: bytes):
    ...

Paths & UUIDs

from pathlib import Path
from uuid import UUID

@mcp.tool()
def operate(path: Path, item_id: UUID):
    ...

Pydantic Models

from pydantic import BaseModel, Field
class User(BaseModel):
    username: str
    email: str = Field(description="Email")

@mcp.tool()
def create_user(user: User):
    ...

Field‑Level Validation Examples

from typing import Annotated
from pydantic import Field

@mcp.tool()
def analyse_metrics(
    count: Annotated[int, Field(ge=0, le=100)],
    ratio: Annotated[float, Field(gt=0, lt=1)],
    user_id: Annotated[str, Field(pattern=r"^[A-Z]{2}\d{4}$")],
    comment: Annotated[str, Field(min_length=3, max_length=500)] = "",
):
    ...

Hyperia returns clear validation errors if input fails constraints.

PreviousResourcesNextPrompts

Last updated