Fix JSON schema generation for complex tool arguments

[rakeshutekar]

Summary

Fix callable tool schema generation so complex Python annotations emit valid JSON Schema instead of stringified Python types.

Problem

Tools._convert_to_tool_spec() manually mapped only primitive types and fell back to str(field_type) for everything else. For annotations like list[str], dict[str, int], or int | None, this produced invalid JSON Schema types such as "list[str]".

Changes

• Use Pydantic’s model_json_schema() for callable tool parameter schemas
• Normalize generated schemas for provider compatibility
• Inline local $defs references
• Remove noisy title fields
• Flatten simple nullable schemas while preserving optionality via defaults/required fields
• Add regression tests for complex tool annotations and execution

Test Plan

PYTHONPATH=. uv run --with pytest --with pydantic --with docstring-parser pytest tests/utils/test_tool_manager.py
PYTHONPATH=. uv run --with pytest --with pydantic --with docstring-parser --with mcp --with nest-asyncio pytest tests/utils/test_tools_mcp_schema.py
PYTHONPATH=. uv run --with pytest --with pydantic --with docstring-parser --with mcp --with nest-asyncio pytest tests/client/test_manual_tool_calling.py

Results:

• tests/utils/test_tool_manager.py: 8 passed
• tests/utils/test_tools_mcp_schema.py: 12 passed
• tests/client/test_manual_tool_calling.py: 4 passed