What causes "Cannot specify name both as first argument and keyword" in PrefectHQ/fastmcp?

Keep only one: drop the name= keyword if the positional string is the desired name

Cannot specify name both as first argument and keyword

Error message

Cannot specify name both as first argument and keyword

What it means

The @tool decorator supports @tool(name) (positional string) or @tool(name=...), but not both. When name_or_fn is a string and the name keyword is also set, it raises TypeError to resolve the ambiguity.

Source

Thrown at fastmcp_slim/fastmcp/tools/function_tool.py:616

            annotations=annotations,
            meta=meta,
            task=task,
            timeout=timeout,
            auth=auth,
            run_in_thread=run_in_thread,
        )
        target = fn.__func__ if isinstance(fn, staticmethod | MethodType) else fn
        cast(Any, target).__fastmcp__ = metadata
        return fn

    def decorator(fn: F, tool_name: str | None) -> F:
        return attach_metadata(fn, tool_name)

    if inspect.isroutine(name_or_fn):
        return decorator(name_or_fn, name)
    elif isinstance(name_or_fn, str):
        if name is not None:
            raise TypeError("Cannot specify name both as first argument and keyword")
        tool_name = name_or_fn
    elif name_or_fn is None:
        tool_name = name
    else:
        raise TypeError(f"Invalid first argument: {type(name_or_fn)}")

    def wrapper(fn: F) -> F:
        return decorator(fn, tool_name)

    return wrapper

View on GitHub (pinned to 1f02114297)

Solutions

Keep only one: drop the name= keyword if the positional string is the desired name
Or drop the positional string and use name="..." only

Example fix

// before
@tool("my_tool", name="my_tool")
def fn(x: int) -> int: ...
// after
@tool("my_tool")
def fn(x: int) -> int: ...

Defensive patterns

Strategy: validation

Validate before calling

def check_tool_decorator_args(name_or_fn, name=None):
    if isinstance(name_or_fn, str) and name is not None:
        raise TypeError('name given both positionally and as keyword')

Try / catch

try:
    tool = tool_decorator('my_tool', name=kw_name)
except TypeError as e:
    if 'both as first argument and keyword' in str(e):
        tool = tool_decorator('my_tool')

Prevention

Use one naming style: prefer @tool(name="...") everywhere
Never forward both *args and name= from wrapper decorators
Lint for @tool calls mixing positional strings with name=

When it happens

Trigger: @tool("my_tool", name="my_tool") or @tool("my_tool", name="other") — any call with a positional string first argument plus a non-None name keyword.

Common situations: Migrating from @tool(name=...) style to positional style and leaving both; IDE autofill adding name= alongside an existing positional name; wrapping decorators forwarding both forms.

Related errors

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/7edd77c10bf8bfc1. Report an issue: GitHub.