Improve Tool Schema Documentation

While experimenting with tool calls, I encountered the following error for the first time:

[Error code: 400 - {'error': {'message': "Invalid 'tools[0].function.description': 
string too long. Expected a string with maximum length 1024, but got a string with length 1239         
instead.", 'type': 'invalid_request_error', 'param': 'tools[0].function.description', 'code':          
'string_above_max_length'}}]

Caused by a purposely long tool description. It would be nice if this limitation was mentioned anywhere at all in the documentation. Never mind subtleties like how the model responds differently to the exact same parameters listed in a different order. I’m not sure why OpenAI seems to believe that developers are interested in reverse-engineering their systems through trial and error, but allow me to correct that misconception.

As always, it would be nice to at least get confirmation that OpenAI is at least aware of some of the challenges devs are facing with the platform.