run-llama/llama_index · error · ValueError

Tool description exceeds maximum length of 1024 characters.

Error message

Tool description exceeds maximum length of 1024 characters. Please shorten your description or move it to the prompt.

What it means

ToolMetadata.to_openai_tool() enforces OpenAI's hard limit of 1024 characters on a function's description field. Descriptions longer than that raise ValueError unless skip_length_check=True is passed, because the OpenAI API would reject the tool definition anyway with a less helpful error.

Source

Thrown at llama-index-core/llama_index/core/tools/types.py:92

    @deprecated(
        "Deprecated in favor of `to_openai_tool`, which should be used instead."
    )
    def to_openai_function(self) -> Dict[str, Any]:
        """
        Deprecated and replaced by `to_openai_tool`.
        The name and arguments of a function that should be called, as generated by the
        model.
        """
        return {
            "name": self._sanitize_name(self.name),
            "description": self.description,
            "parameters": self.get_parameters_dict(),
        }

    def to_openai_tool(self, skip_length_check: bool = False) -> Dict[str, Any]:
        """To OpenAI tool."""
        if not skip_length_check and len(self.description) > 1024:
            raise ValueError(
                "Tool description exceeds maximum length of 1024 characters. "
                "Please shorten your description or move it to the prompt."
            )
        return {
            "type": "function",
            "function": {
                "name": self._sanitize_name(self.name),
                "description": self.description,
                "parameters": self.get_parameters_dict(),
            },
        }


class ToolOutput(BaseModel):
    """Tool output."""

    blocks: List[ContentBlock]
    tool_name: str

View on GitHub (pinned to afd0fef371)

Solutions

1. Shorten the description to under 1024 characters and move usage guidance into the system prompt.
2. If you accept the risk of provider-side rejection (or target a non-OpenAI provider via the OpenAI schema), call to_openai_tool(skip_length_check=True).
3. Cap auto-generated descriptions: description=docstring[:1000].

Example fix

# before
 tool = FunctionTool.from_defaults(fn=search, description=LONG_TEXT)  # >1024 chars
 payload = tool.metadata.to_openai_tool()  # ValueError

# after
 tool = FunctionTool.from_defaults(fn=search, description=LONG_TEXT[:1000])
 payload = tool.metadata.to_openai_tool()  # ok
 # or: tool.metadata.to_openai_tool(skip_length_check=True)

MAX_DESC = 1024

def clamp_description(description: str) -> str:
    if len(description) > MAX_DESC:
        # move overflow into prompt context elsewhere
        return description[:MAX_DESC - 1]
    return description

# usage: tool.metadata.to_openai_tool() is now safe

def description_within_limit(metadata, limit: int = 1024) -> bool:
    return len(metadata.description or '') <= limit

try:
    payload = tool.metadata.to_openai_tool()
except ValueError as e:
    if 'maximum length' in str(e):
        payload = tool.metadata.to_openai_tool(skip_length_check=True)  # only for non-OpenAI targets
    else:
        raise

When it happens

Trigger: Calling tool.metadata.to_openai_tool() (directly, or via an OpenAI LLM/agent that converts tools at request time) when the tool's description text exceeds 1024 chars - e.g. a long RAG description, embedded few-shot examples, or a docstring copied verbatim into description.

Common situations: Using a retriever/tool whose description includes extensive context injection; auto-generating descriptions from long function docstrings; switching an agent to an OpenAI model and suddenly hitting the limit that other providers don't enforce.

Related errors

• Tool name cannot be None
• fn_schema is None.
• name is None.
• Unexpected type: {type(choice)}
• `llama-index-embeddings-openai` package not found, please ru

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/b9855c5bfbf5972a. Report an issue: GitHub.