OpenAPI spec with component references does not properly import descriptions

[ianmcvann]

Description

I'm seeing a slightly odd behavior with how FastMCP seems to be handling recursive references in OpenAPI spec.

Take the JSON attached below, I would expect that it would extract the description from the format field and list it within component.description, but it seems to ignore it entirely. If I move the element in line though and remove references it works as expected.

Example Code

{
  "openapi": "3.0.0",
  "info" : {
    "description" : "Example Spec",
    "title" : "Example API",
    "version" : "1.0"
  },
    "servers" : [ {
    "description" : "Example API",
    "url" : "https://api.example.com"
  } ],
  "paths": {
    "/api/v1/test" : {
      "post" : {
        "description" : "Test",
        "operationId" : "test_post",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/test_request_schema"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "OK"
            }
          }
        }
  }},
  "components": {
    "schemas": {
      "test_request_schema": {
        "properties": {
          "format": {
              "$ref" : "#/components/schemas/format"
            }
        }
      },
      "format" : {
        "default" : "1",
        "description" : "Test description",
        "enum" : [ "1", "2", "3", "4" ],
        "example" : "1",
        "title" : "format",
        "type" : "string"
      }
    }
  }
  }

Version Information

FastMCP version:                                                                                2.9.0
MCP version:                                                                                    1.9.4
Python version:                                                                               3.11.13
Platform:                                                                  macOS-15.0-arm64-arm-64bit
FastMCP root path: /Users/ianmcvann/Documents/netography/neto-mcp-server/.venv/lib/python3.11/s

Additional Context

No response

[jlowin]

Thanks for the spec - #897 (@owtaylor) attempted to address some of this but was included in 2.9 so maybe this is a new wrinkle. Will have to investigate.

[owtaylor]

Is it possible for you to include the generated tool definition? This looks like a pretty straightforward example similar to my use case and what is tested in the tests - it's not obvious to me what is different or what the exact breakage is.

[ianmcvann]

`INFO:fastmcp.utilities.openapi:Successfully parsed OpenAPI 3.0 schema version: 3.0.0
INFO:fastmcp.utilities.openapi:Successfully extracted route: POST /api/v1/test
INFO:fastmcp.utilities.openapi:Finished parsing. Extracted 1 HTTP routes.
Test

Responses:

• 200 (Success): OK
  [06/23/25 13:28:34] INFO Created FastMCP OpenAPI server with 1 routes`

Here's the component.description, would expect it to have the required request body

[owtaylor]

What I'm interested in is what is the tool call description that the OpenAPI spec has been converted to - so, for example, if you can enable logging of what is sent to the model by your client, you'll see the client sending the model it.

[ianmcvann]

I can get that, but normally you would see the request parameters here in the description.

[owtaylor]

So it sounds like the bug is perhaps with what is being logged rather than how the MCP is working? When I use your API spec and create a MCP from it, what I see being sent to the model for the tool definition is:

    {
      "displayTitle": "Test test_post",
      "function": {
        "description": "Test\n\n\n**Responses:**\n\n- **200** (Success): OK",
        "name": "test_post",
        "parameters": {
          "type": "object",
          "properties": {
            "format": {
              "$ref": "#/$defs/format"
            }
          },
          "required": [],
          "$defs": {
            "format": {
              "title": "format",
              "enum": [
                "1",
                "2",
                "3",
                "4"
              ],
              "type": "string",
              "description": "Test description",
              "default": "1",
              "example": "1"
            }
          }
        }
      },
      "readonly": false,
      "type": "function",
      "uri": "mcp://Test/test_post",
      "group": "Test"
    }

Which looks at least very plausible.

[ianmcvann]

The description needs have the request parameters. Otherwise when you call it you'll get this, which is incorrect:

For in line components FastMCP adds a request parameters section to the description, it should also do that in this case (at least to my understanding).

[owtaylor]

What client are you using? What model? Via what API?

[ianmcvann]

LibreChat, ChatGPT 4o, Azure.

fastmcp/src/fastmcp/utilities/openapi.py

Line 770 in 691e047

# Add request body information if present

here's where the issue is, this handling looks for a description field but doesn't check references.

[owtaylor]

Ah, OK, now if I reread your earlier messages, I understand what you are saying - the problem isn't with the JSON schema (which is what #897 fixes), but with the "enhanced description". If this is causing the model to misbehave in the way you describe, this might indicate a problem with LibreChat - maybe it's just passing along the description without the json schema? Still, it would be better if the description is correct - it shouldn't be different if properties are defined inline or via reference.

This could be fixed by either:

• Adding lookups in $defs to the description code [simpler]
• Inline references to $defs where possible. [somewhat more complicated - it's hard to predict it would improve the quality of model responses or make them worse]