Unknown arguments in transform_args: {', '.join(sorted(unkno

Error message

Unknown arguments in transform_args: {', '.join(sorted(unknown_args))}. Parent tool `{tool.name}` has: {', '.join(sorted(parent_params))}

What it means

from_tool() validates that every key in transform_args corresponds to an actual parameter of the parent tool. Unknown keys would silently do nothing, so it raises ValueError listing the unknown arguments and the parent tool's actual parameter names.

Source

Thrown at fastmcp_slim/fastmcp/tools/tool_transform.py:497

                    content=[TextContent(text="Summary")],
                    structured_content={"processed": True}
                )
            ```
        """
        tool = Tool._ensure_tool(tool)

        transform_args = transform_args or {}

        if transform_fn is not None:
            parsed_fn = ParsedFunction.from_function(transform_fn, validate=False)
        else:
            parsed_fn = None

        # Validate transform_args
        parent_params = set(tool.parameters.get("properties", {}).keys())
        unknown_args = set(transform_args.keys()) - parent_params
        if unknown_args:
            raise ValueError(
                f"Unknown arguments in transform_args: {', '.join(sorted(unknown_args))}. "
                f"Parent tool `{tool.name}` has: {', '.join(sorted(parent_params))}"
            )

        # Always create the forwarding transform
        schema, forwarding_fn = cls._create_forwarding_transform(tool, transform_args)

        # Handle output schema
        if output_schema is NotSet:
            # Use smart fallback: try custom function, then parent
            if transform_fn is not None:
                # parsed fn is not none here
                final_output_schema = cast(ParsedFunction, parsed_fn).output_schema
                if final_output_schema is None:
                    # Check if function returns ToolResult (or subclass) - if so, don't fall back to parent.
                    # Use parsed_fn.return_type (resolved via get_type_hints) instead of
                    # inspect.signature, which returns strings under `from __future__ import annotations`.
                    return_type = cast(ParsedFunction, parsed_fn).return_type

View on GitHub (pinned to 1f02114297)

Solutions

Check the error's 'Parent tool has:' list and rename transform_args keys to match exactly.
Print tool.parameters["properties"] for the parent to confirm parameter names.
Remove transform_args entries that no longer exist after a parent tool upgrade.

Example fix

// before
ParentTool.from_tool(tool, transform_args={"query_str": ArgTransform(name="q")})

// after (parent param is 'query')
ParentTool.from_tool(tool, transform_args={"query": ArgTransform(name="q")})

Defensive patterns

Strategy: validation

Validate before calling

def check_transform_args(tool, transform_args: dict) -> None:
    parent_params = set(tool.parameters.get("properties", {}).keys())
    unknown = set(transform_args) - parent_params
    if unknown:
        raise ValueError(f"Unknown transform_args keys: {sorted(unknown)}; parent has {sorted(parent_params)}")

Try / catch

try:
    t = ParentTool.from_tool(tool, transform_args=ta)
except ValueError as e:
    if "Unknown arguments" in str(e):
        log.error("Fix transform_args keys against parent schema: %s", e)
    raise

Prevention

Copy parameter names directly from tool.parameters['properties'] rather than typing them.
Re-validate transform_args after any parent tool signature/version change.
Keep transform definitions adjacent to the parent tool definition so renames stay in sync.

When it happens

Trigger: Passing transform_args={"typo_param": ArgTransform(...)} where the parent tool's schema properties don't include that name; transforming a tool whose parameter names changed between library versions; renaming a parent parameter without updating transform_args.

Common situations: Typos in parameter names; building transforms against an old parent tool signature; parent tool updated upstream (version change) and transform_args no longer matches.

Related errors

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