huggingface/smolagents · error · ValueError

Tool call needs to have a key '{tool_name_key}'. Got keys: {

Error message

Tool call needs to have a key '{tool_name_key}'. Got keys: {list(tool_call_dictionary.keys())} instead

What it means

For models that return tool calls as JSON text, smolagents parses the blob and requires it to contain the tool name under the configured tool_name_key (default 'name', set by tool_call_parser / model config). If the key is absent (or the blob isn't a dict mapping with that key), the KeyError is converted to ValueError listing the keys actually found. The tool_arguments_key (default 'arguments') is optional and defaults to None.

Source

Thrown at src/smolagents/models.py:405

            if flatten_messages_as_text:
                content = message.content[0]["text"]
            else:
                content = message.content
            output_message_list.append(
                {
                    "role": message.role,
                    "content": content,
                }
            )
    return output_message_list


def get_tool_call_from_text(text: str, tool_name_key: str, tool_arguments_key: str) -> ChatMessageToolCall:
    tool_call_dictionary, _ = parse_json_blob(text)
    try:
        tool_name = tool_call_dictionary[tool_name_key]
    except Exception as e:
        raise ValueError(
            f"Tool call needs to have a key '{tool_name_key}'. Got keys: {list(tool_call_dictionary.keys())} instead"
        ) from e
    tool_arguments = tool_call_dictionary.get(tool_arguments_key, None)
    if isinstance(tool_arguments, str):
        tool_arguments = parse_json_if_needed(tool_arguments)
    return ChatMessageToolCall(
        id=str(uuid.uuid4()),
        type="function",
        function=ChatMessageToolCallFunction(name=tool_name, arguments=tool_arguments),
    )


def supports_stop_parameter(model_id: str) -> bool:
    """
    Check if the model supports the `stop` parameter.

    Not supported with reasoning models openai/o3, openai/o4-mini, and the openai/gpt-5 series (and their versioned variants).

View on GitHub (pinned to 30bb116109)

Solutions

Align the model's tool-call JSON format with the parser: include the expected name key (e.g. {'name': ..., 'arguments': ...})
Adjust the system prompt/tool-call template so the model outputs the required keys
If the model uses different keys consistently, configure the parser's tool_name_key accordingly or wrap the model to remap keys
Retry/regenerate: LLMs occasionally omit keys; feeding the error back often fixes it

Example fix

# before (model output)
{"action": "get_weather", "action_input": {"city": "Paris"}}

# after (model output)
{"name": "get_weather", "arguments": {"city": "Paris"}}

Defensive patterns

Strategy: fallback

Validate before calling

from smolagents.utils import parse_json_blob
parsed, _ = parse_json_blob(text)
if 'name' not in parsed:
    text = f"{{\"name\": {parsed.get('action')}, \"arguments\": {parsed.get('action_input')}}}"

Type guard

def has_tool_name_key(text: str, key: str = 'name') -> bool:
    try:
        blob, _ = parse_json_blob(text)
        return isinstance(blob, dict) and key in blob
    except Exception:
        return False

Try / catch

try:
    tool_call = get_tool_call_from_text(text, 'name', 'arguments')
except ValueError as e:
    if 'Tool call needs to have a key' in str(e):
        text = regenerate_with_feedback(text, str(e))  # ask LLM to fix JSON

Prevention

Align the system prompt's tool-call JSON template with the parser keys
When swapping models, verify their JSON output keys match 'name'/'arguments'
Add a retry-with-error-feedback loop for malformed tool-call JSON

When it happens

Trigger: A model emitting JSON like {"action": "final_answer", "action_input": ...} while the parser expects {'name': ..., 'arguments': ...}, or any tool-call JSON missing the configured name key; triggered via parse_tool_calls during chat post-processing.

Common situations: Using a custom/HF Inference model whose prompt format differs from the parser's expected key names; switching models without updating the tool call template; LLM emitting malformed or differently-keyed JSON.

Related errors

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/b181f788ad11a5ef. Report an issue: GitHub.