{"record":{"id":"b9855c5bfbf5972a","repo":"run-llama/llama_index","slug":"tool-description-exceeds-maximum-length-of-1024-ch","errorCode":null,"errorMessage":"Tool description exceeds maximum length of 1024 characters. Please shorten your description or move it to the prompt.","messagePattern":"Tool description exceeds maximum length of 1024 characters\\. Please shorten your description or move it to the prompt\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/tools/types.py","lineNumber":92,"sourceCode":"    @deprecated(\n        \"Deprecated in favor of `to_openai_tool`, which should be used instead.\"\n    )\n    def to_openai_function(self) -> Dict[str, Any]:\n        \"\"\"\n        Deprecated and replaced by `to_openai_tool`.\n        The name and arguments of a function that should be called, as generated by the\n        model.\n        \"\"\"\n        return {\n            \"name\": self._sanitize_name(self.name),\n            \"description\": self.description,\n            \"parameters\": self.get_parameters_dict(),\n        }\n\n    def to_openai_tool(self, skip_length_check: bool = False) -> Dict[str, Any]:\n        \"\"\"To OpenAI tool.\"\"\"\n        if not skip_length_check and len(self.description) > 1024:\n            raise ValueError(\n                \"Tool description exceeds maximum length of 1024 characters. \"\n                \"Please shorten your description or move it to the prompt.\"\n            )\n        return {\n            \"type\": \"function\",\n            \"function\": {\n                \"name\": self._sanitize_name(self.name),\n                \"description\": self.description,\n                \"parameters\": self.get_parameters_dict(),\n            },\n        }\n\n\nclass ToolOutput(BaseModel):\n    \"\"\"Tool output.\"\"\"\n\n    blocks: List[ContentBlock]\n    tool_name: str","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/tools/types.py#L74-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Shorten the description to under 1024 characters and move usage guidance into the system prompt.","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).","Cap auto-generated descriptions: description=docstring[:1000]."],"exampleFix":"# before\n tool = FunctionTool.from_defaults(fn=search, description=LONG_TEXT)  # >1024 chars\n payload = tool.metadata.to_openai_tool()  # ValueError\n\n# after\n tool = FunctionTool.from_defaults(fn=search, description=LONG_TEXT[:1000])\n payload = tool.metadata.to_openai_tool()  # ok\n # or: tool.metadata.to_openai_tool(skip_length_check=True)","handlingStrategy":"validation","validationCode":"MAX_DESC = 1024\n\ndef clamp_description(description: str) -> str:\n    if len(description) > MAX_DESC:\n        # move overflow into prompt context elsewhere\n        return description[:MAX_DESC - 1]\n    return description\n\n# usage: tool.metadata.to_openai_tool() is now safe","typeGuard":"def description_within_limit(metadata, limit: int = 1024) -> bool:\n    return len(metadata.description or '') <= limit","tryCatchPattern":"try:\n    payload = tool.metadata.to_openai_tool()\nexcept ValueError as e:\n    if 'maximum length' in str(e):\n        payload = tool.metadata.to_openai_tool(skip_length_check=True)  # only for non-OpenAI targets\n    else:\n        raise","preventionTips":["Cap descriptions at authoring time, not conversion time.","Put usage instructions in the system prompt, not the tool description.","When auto-generating descriptions from docstrings, slice to ~1000 chars."],"tags":["openai","tool-metadata","length-limit","value-error"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}