Tools

Tools are the functions your MCP server exposes to AI assistants. When an LLM decides it needs to perform an action—like searching documents, creating issues, or fetching data—it calls one of your tools. You can use FastMCP (recommended) or the low-level Server API. Both are fully supported.

Basic Tool

Here’s a simple tool that searches documents. Notice the type annotations and docstring—these are essential for LLMs to understand and use your tool correctly.

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("my-server")

class SearchResult(BaseModel):
    title: str
    url: str
    snippet: str

@mcp.tool()
async def search(query: str = Field(description="Search query")) -> list[SearchResult]:
    """Search for documents matching the query."""
    # Implementation
    return results

Requirements

Every tool needs a few things to work properly with Gumstack and LLMs. Missing any of these will cause issues.

Declare in config.yaml

Every tool must be declared in config.yaml:

tools:
  - name: "search"
    description: "Search for documents"

The name must match your function name exactly. Without this, Gumstack won’t detect the tool.

Return type annotation

Every tool must have a return type. This generates the output schema that Gumloop uses for node connections.

# Good - typed return
@mcp.tool()
def get_user(id: str) -> User:
    ...

# Bad - no schema generated, breaks Gumloop
@mcp.tool()
def get_user(id: str):
    return {"name": "John"}

Docstrings

LLMs use docstrings to decide when to call your tool. Be specific:

# Good
@mcp.tool()
def create_issue(title: str, body: str) -> Issue:
    """Create a new issue in the project tracker.

    Use this when the user wants to report a bug or request a feature.
    """

# Bad - too vague
@mcp.tool()
def create_issue(title: str, body: str) -> Issue:
    """Create an issue."""

Parameter descriptions

Use Annotated with a string or Field(description=...):

from typing import Annotated
from pydantic import Field

@mcp.tool()
def search(
    query: Annotated[str, "Keywords to search for"],
    limit: Annotated[int, Field(description="Max results", ge=1, le=100)] = 10
) -> list[SearchResult]:
    """Search documents."""

Supported types

FastMCP supports all Pydantic types:

Type	Example
Basic	`int`, `float`, `str`, `bool`
Collections	`list[str]`, `dict[str, int]`
Optional	`str \| None`, `Optional[str]`
Constrained	`Literal["A", "B"]`, `Enum`
Pydantic models	`User`, `SearchResult`
Date/time	`datetime`, `date`
Paths	`Path`

Common Mistakes

These patterns cause problems in production. Avoid them to keep your tools reliable and debuggable.

Bare dict returns

# Bad - no output schema
@mcp.tool()
def get_data() -> dict:
    return {"key": "value"}

# Good - typed dict or BaseModel

@mcp.tool()
def get_data() -> dict[str, str]:
return {"key": "value"}

Blocking I/O in async

# Bad - blocks event loop
@mcp.tool()
async def fetch(url: str) -> str:
    return requests.get(url).text

# Good - use async HTTP client
@mcp.tool()
async def fetch(url: str) -> str:
    async with httpx.AsyncClient() as client:
        resp = await client.get(url)
        return resp.text

Hardcoded credentials

# Bad
API_KEY = "sk-..."

# Good

creds = await get_credentials()
api_key = creds["api_key"]

Swallowing exceptions

# Bad - hides errors from observability
try:
    result = do_thing()
except Exception:
    return "Error occurred"

# Good - let errors propagate
result = do_thing()  # Gumstack logs the error

One Tool, One Job

Resist the urge to create “swiss army knife” tools that do multiple things. Split complex operations into focused tools for better:

Observability — See exactly which operation failed
Access control — Admins can restrict specific actions
LLM accuracy — Simpler tools are easier to use correctly

# Instead of one mega-tool
@mcp.tool()
def manage_issues(action: str, issue_id: str = None, title: str = None):
    ...

# Split into focused tools
@mcp.tool()
def list_issues() -> list[Issue]: ...

@mcp.tool()
def create_issue(title: str, body: str) -> Issue: ...

@mcp.tool()
def close_issue(issue_id: str) -> Issue: ...

Low-level Server API

FastMCP handles most use cases, but if you need fine-grained control over tool registration and responses, you can use the low-level Server class directly:

from mcp.server.lowlevel.server import Server
import mcp.types as types

server = Server("my-server")

@server.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="greet",
            description="Say hello",
            inputSchema={"type": "object", "properties": {"name": {"type": "string"}}}
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "greet":
        return [types.TextContent(type="text", text=f"Hello, {arguments['name']}!")]

See the MCP Python SDK and FastMCP docs for full API reference.

Get Started

Platform

Building Servers

Security

Deployment

Reference

Basic Tool

Requirements

Declare in config.yaml

Return type annotation

Docstrings

Parameter descriptions

Supported types

Common Mistakes

One Tool, One Job

Low-level Server API

​Basic Tool

​Requirements

​Declare in config.yaml

​Return type annotation

​Docstrings

​Parameter descriptions

​Supported types

​Common Mistakes

​One Tool, One Job

​Low-level Server API

Basic Tool

Requirements

Declare in config.yaml

Return type annotation

Docstrings

Parameter descriptions

Supported types

Common Mistakes

One Tool, One Job

Low-level Server API