Repository navigation
createBooking tool schema has unresolved $defs references and is rejected by LLM providers #8
Description
Summary
When using @calcom/cal-mcp@latest, the MCP server exposes the createBooking tool, but the generated input schema appears to contain $ref references to $defs entries that are not included in the final tool parameter schema sent to the LLM.
This causes LLM providers to reject the tool before any tool call can happen.
The most direct error is from Groq/OpenAI-compatible tool calling:
invalid JSON schema for tool createBooking, tools[1].function.parameters:
jsonschema file:///home/di/params.json compilation failed:
file:///home/di/params.json#/$defs/CreateBookingInput_2024_08_13 not foundThis looks like the schema contains a reference like:
{
"$ref": "#/$defs/CreateBookingInput_2024_08_13"
}but the corresponding $defs.CreateBookingInput_2024_08_13 definition is missing from the schema provided for createBooking.
Reproduction
I am using the Cal.com MCP server through stdio:
from mcp import StdioServerParameters
from pipecat.services.mcp_service import MCPClient
async with MCPClient(
server_params=StdioServerParameters(
command="npx",
args=["-y", "@calcom/cal-mcp@latest"],
env={**os.environ, "CAL_API_KEY": os.environ["CAL_API_KEY"]},
),
tools_filter=[
"getEventTypes",
"getEventTypeById",
"createBooking",
"getBookings",
"getBooking",
"rescheduleBooking",
"cancelBooking",
],
) as mcp:
tools = await mcp.register_tools(llm)The MCP server starts successfully and exposes the expected tools, including:
cancelBooking
createBooking
getBooking
getBookings
getEventTypeById
getEventTypes
rescheduleBookingHowever, as soon as the LLM request is made with createBooking included in the tool list, the provider rejects the tool schema.
Actual behavior
With Groq/OpenAI-compatible tool calling, the request fails before the model responds:
GroqLLMService#0: Generating chat from context [{'role': 'developer', 'content': 'Start by concisely introducing yourself.'}]
GroqLLMService#0 exception:
Error during completion: Error code: 400 - {
'error': {
'message': 'invalid JSON schema for tool createBooking, tools[1].function.parameters: jsonschema file:///home/di/params.json compilation failed: file:///home/di/params.json#/$defs/CreateBookingInput_2024_08_13 not found',
'type': 'invalid_request_error',
'param': 'tool createBooking, tools[1].function.parameters'
}
}With Google Gemini, a related schema validation failure happens because the booking tools contain $ref inside anyOf:
GoogleLLMService#0 exception:
Unknown error occurred: 11 validation errors for GenerateContentConfig
tools.0.Tool.function_declarations.1.parameters.properties.body.anyOf.0.$ref
Extra inputs are not permitted
input_value='#/$defs/CreateBookingInput_2024_08_13'
tools.0.Tool.function_declarations.1.parameters.properties.body.anyOf.1.$ref
Extra inputs are not permitted
input_value='#/$defs/CreateInstantBookingInput_2024_08_13'
tools.0.Tool.function_declarations.1.parameters.properties.body.anyOf.2.$ref
Extra inputs are not permitted
input_value='#/$defs/CreateRecurringBookingInput_2024_08_13'Similar $ref validation errors also appear for:
RescheduleBookingInput_2024_08_13
RescheduleSeatedBookingInput_2024_08_13
CancelBookingInput_2024_08_13
CancelSeatedBookingInput_2024_08_13Expected behavior
The MCP server should expose LLM-compatible JSON schemas for booking tools.
Specifically, createBooking, rescheduleBooking, and cancelBooking should not contain unresolved references.
Either:
- The referenced definitions should be included in the schema:
{
"$defs": {
"CreateBookingInput_2024_08_13": {}
}
}or:
- The schema should be dereferenced/inlined before being exposed as an MCP tool schema.
Ideally, the generated tool schema should be compatible with common LLM tool/function calling providers such as OpenAI-compatible APIs, Groq, Gemini, Anthropic, etc.
Environment
@calcom/cal-mcp: latest via npx -y @calcom/cal-mcp@latest
MCP client: Python MCP SDK / Pipecat MCPClient
Pipecat: 1.3.0
Python: 3.14
mcp Python package: 1.27.2
LLM providers tested:
- Groq / OpenAI-compatible tool calling
- Google Gemini
Activity