Tool Naming

FastAPI-MCP uses the operation_id from your FastAPI routes as the names for the generated MCP tools. A clear and descriptive operation_id is crucial for helping the LLM understand and correctly choose the right tool for a given task.

If you do not specify an operation_id for a route, FastAPI will auto-generate one based on the function name and path. While functional, these auto-generated names can be cryptic and less intuitive for an LLM.

Example: Auto-Generated vs. Explicit operation_id

Consider the following two endpoint definitions:

from fastapi import FastAPI

app = FastAPI()

# 1. Endpoint with an auto-generated operation_id
# FastAPI will generate an ID like: 'read_user_users__user_id__get'
# The resulting MCP tool will be named 'read_user_users__user_id__get'
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# 2. Endpoint with an explicit, descriptive operation_id
# The resulting MCP tool will be named 'get_user_by_id'
@app.get("/user_info/{user_id}", operation_id="get_user_by_id")
async def get_user_information(user_id: int):
    return {"user_id": user_id}

The second endpoint, with operation_id="get_user_by_id", produces a much clearer tool name for an LLM to interpret.

Best Practices for Tool Naming

  • Be Explicit: Always provide an operation_id for routes you intend to expose as MCP tools.
  • Be Descriptive: Use clear, verb-first names that accurately describe what the tool does (e.g., get_user_profile, create_invoice, search_products_by_category).
  • Be Consistent: Use a consistent naming convention (e.g., snake_case or camelCase) across all your tools.

For more information on path operation configuration in FastAPI, refer to the official FastAPI documentation.