sequentialthinking tool description beyond OpenAI length limitation #799
Description
Describe the bug
The length of the description of the sequentialthinking server is longer than the max allowed length of tool descriptions when using some OpenAI models.
To Reproduce
Steps to reproduce the behavior:
- Pass the description of the sequentialthinking tool as part of a tool-enabled inference request to
gpt4o-mini.
Expected behavior
No errors, and the LLM is able to use the sequentialthinking tool
Logs
In my case, I am using a client to send the completion requests, and that client uses the tool descriptions provided via the MCP server protocol to format the completion requests. When using sequentialthinking tool with gpt40-mini, due to the length of its description, errors happen such as:
- body: {
"error": {
"message": "Invalid 'tools[26].function.description': string too long. Expected a string with maximum length 1024, but got a string with length 2780 instead.",
"type": "invalid_request_error",
"param": "tools[26].function.description",
"code": "string_above_max_length"
}
}
I cannot find any official documentation of this limitation.
Reacted by Mike Webb, Bjørn Kristian Punsvik, Seito Tanaka and privetin
Activity
olafgeibig commentedon Apr 11, 2025
Were you trying to use the sequential-thinking MCP server with Azure OpenAI? Because my error message looked exactly like yours. Unfortunately, Azure OpenAI has a 1024 characters limit for tool descriptions. You can find a lot of problem reports about that on the net. So I copied the original code and introduced a workaround.
https://github.com/olafgeibig/sequential-thinking-azure
My workaround introduces a second tool method that returns the lengthy description and shortens the description of teh actual thinking tool method. In the description of the thinking method, it is required to call the instruction method first. This is kind of a hacky workaround, but in my testing it works well. This is the reason why I did not create a PR against the OG repo. My version is significantly different and may not work in certain scenarios.
@jamesfalkner this is most probably not a bug in your code. This is an actual limitation of Azure OpenAI
yifanyifan897645 commentedon Mar 30, 2026
Long tool descriptions are a widespread problem. We built mcp-checkup which flags tools with excessively long descriptions and counts their token cost. Helps MCP server authors catch these issues during development.
npx mcp-checkupjashshah999 commentedon May 5, 2026
Schema length issues like this are catchable before shipping with automated linting. I built mcpeval which flags tool descriptions over 500 chars and shows you token-by-token budget breakdown per tool. Would have caught this before it hit OpenAI's limit.
mcpeval check server.json # Shows per-tool token usage + warns on oversized descriptionsPengSpirit commentedon May 20, 2026
test(sequentialthinking): mark the tests that pin known bugs
test(sequentialthinking): in-process protocol suite and per-file 90% …
cliffhall commentedon Oct 19, 2026
Triage: Priority Low (total 4)
Still present on v2 (checked by reading the current code).
Board: Servers V2 (#43), Status
Incoming, awaiting maintainer review (no milestone yet). Part of the backlog triage in #4875.cliffhall commentedon Oct 20, 2026
Prior work, from the PR backlog triage (#4877). These outside pull requests addressed this issue against the pre-refactor code:
They are being closed as part of the backlog triage in #4875, since the repository now takes issues rather than outside PRs and their diffs predate the v2 refactor. They stay readable and serve as prototypes for the fix here. Thank you to their authors.
cliffhall commentedon Oct 29, 2026
Fixed by #5374, merged into
v2/main. Ships in v2.3.0.feat(sequentialthinking): trim the tool description to fit 1024 chara…