fix(core): improve error message for non-JSON-serializable tool schemas

[Tanzim Hossain Romel (thromel)]

Summary

When a Pydantic model with arbitrary_types_allowed=True contains custom Python classes that cannot be converted to JSON schema, users previously received a cryptic PydanticInvalidForJsonSchema error from deep in Pydantic's internals.

This change catches PydanticInvalidForJsonSchema in _convert_pydantic_to_openai_function() and re-raises as a TypeError with a helpful message that:

• Names the model that failed
• Explains that tool argument schemas must be JSON-serializable
• Suggests concrete solutions (convert to Pydantic models, use primitive types, or serialize to JSON strings)
• Links to the custom tools documentation

Example of new error message

TypeError: Failed to generate JSON schema for 'ToolInputSchema': Cannot generate a JsonSchema for core_schema.IsInstanceSchema (<class '__main__.Mohan'>)

Tool argument schemas must be JSON-serializable. If your schema includes custom Python classes, consider:
  1. Converting them to Pydantic models with JSON-compatible fields
  2. Using primitive types (str, int, float, bool, list, dict) instead
  3. Passing the data as serialized JSON strings

For more information, see: https://python.langchain.com/docs/how_to/custom_tools/

Test plan

• Added unit test test_convert_to_openai_function_arbitrary_type_error that verifies the improved error message is raised
• All existing tests in test_function_calling.py pass

Fixes #34371

[codspeed-hq]

Merging this PR will improve performance by 35.11%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚡ 13 improved benchmarks
⏩ 23 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	WallTime	test_import_time[LangChainTracer]	487.6 ms	419.7 ms	+16.18%
⚡	WallTime	test_import_time[HumanMessage]	287.6 ms	240.1 ms	+19.76%
⚡	WallTime	test_import_time[InMemoryVectorStore]	659.2 ms	542.4 ms	+21.53%
⚡	WallTime	test_async_callbacks_in_sync	24.5 ms	18.1 ms	+35.11%
⚡	WallTime	test_import_time[CallbackManager]	344.5 ms	289.6 ms	+18.96%
⚡	WallTime	test_import_time[tool]	601.5 ms	477.9 ms	+25.88%
⚡	WallTime	test_import_time[ChatPromptTemplate]	680.4 ms	551.8 ms	+23.32%
⚡	WallTime	test_import_time[BaseChatModel]	580.6 ms	479.6 ms	+21.07%
⚡	WallTime	test_import_time[InMemoryRateLimiter]	184 ms	161.4 ms	+14.03%
⚡	WallTime	test_import_time[Document]	201 ms	169.8 ms	+18.33%
⚡	WallTime	test_import_time[PydanticOutputParser]	583.2 ms	486.5 ms	+19.86%
⚡	WallTime	test_import_time[Runnable]	533.9 ms	447.9 ms	+19.21%
⚡	WallTime	test_import_time[RunnableLambda]	540.3 ms	461.7 ms	+17.03%

---

_{Comparing thromel:fix/pydantic-json-schema-error (32a1e52) with master (d6e46bb)}

Footnotes

1. 23 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[ccurme (ccurme)]

this inherits TypeError