What causes "name is required when using define_tool with handler=" in github/copilot-sdk?

Pass name='my_tool' to define_tool when supplying handler=.

github/copilot-sdk · error · ValueError

name is required when using define_tool with handler=

Error message

name is required when using define_tool with handler=

What it means

define_tool() builds a Tool registration helper. When a handler function is passed positionally via handler=, the SDK calls the decorator immediately, which requires a tool name; without one it raises this ValueError. Decorator-only usage (@define_tool() without handler) gets the name from the decorated function instead.

Solutions

Pass name='my_tool' to define_tool when supplying handler=.
Or drop handler= and use define_tool as a decorator so the function name is inferred: @define_tool(name=None is allowed via @define_tool()).
If registering dynamically, validate the configured tool name exists before calling define_tool.

Example fix

// before
tool = define_tool(handler=search_docs, params_type=SearchParams)
// after
tool = define_tool(name='search_docs', handler=search_docs, params_type=SearchParams)

Defensive patterns

Strategy: validation

Validate before calling

assert name and isinstance(name, str), 'define_tool requires name= when handler= is passed'

Try / catch

try:
    tool = define_tool(handler=fn, params_type=Model)
except ValueError as exc:
    if 'name is required' in str(exc):
        tool = define_tool(name=fn.__name__, handler=fn, params_type=Model)
    else:
        raise

Prevention

Always pass name= when using the direct-call form with handler=.
Prefer the decorator form @define_tool() so the function name is inferred.
Validate dynamically configured tool names before registration.
Add a unit test per registered tool so a missing-name regression fails at test time.

When it happens

Trigger: Calling copilot.tools.define_tool(handler=my_func) or define_tool(params_type=..., handler=my_func) without passing name=; i.e. any immediate-invocation form that omits name.

Common situations: Migrating from a decorator style call to passing handler directly while forgetting name; dynamically registering tools from a config where the name key is missing; copying a @define_tool(params_type=Model) decorator example and adding handler= without adding name=.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/50b3ba1cfb85605a. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/tools.py:314

                    _from_exception=True,
                )

        return Tool(
            name=tool_name,
            description=description or "",
            parameters=schema,
            handler=wrapped_handler,
            overrides_built_in_tool=overrides_built_in_tool,
            skip_permission=skip_permission,
            defer=defer,
            metadata=metadata,
            is_terminal=is_terminal,
        )

    # If handler is provided, call decorator immediately
    if handler is not None:
        if name is None:
            raise ValueError("name is required when using define_tool with handler=")
        return decorator(handler)

    # If a parameter model is provided without a handler, expose a declaration-only tool.
    if name is not None and params_type is not None:
        schema = params_type.model_json_schema() if _is_pydantic_model(params_type) else None
        return Tool(
            name=name,
            description=description or "",
            parameters=schema,
            handler=None,
            overrides_built_in_tool=overrides_built_in_tool,
            skip_permission=skip_permission,
            defer=defer,
            metadata=metadata,
            is_terminal=is_terminal,
        )

    # Otherwise return decorator for @define_tool(...) usage

View on GitHub (pinned to cd8cf15dc3)