Skip to content

The LLM version of the schema is full of noisy html and confuses agents #2239

@jakemac53

Description

@jakemac53

Describe the bug
See https://modelcontextprotocol.io/specification/2025-11-25/schema.md - this file is currently very long and mostly just html tags, making it not very helpful for LLMs.

When pointing my agent at it in order to update to the latest schema, it ended up just inventing a bunch APIs on Task etc, and I think its because it couldn't make any sense of it.

To Reproduce
Try pointing your agent to https://modelcontextprotocol.io/specification/2025-11-25/schema.md and ask it to give you the exact schema for the Task type.

Expected behavior
I expected this file to be in a format that an LLM can successfully consume. It should have minimal tokens and little or no HTML.

Logs
If applicable, add logs to help explain your problem.

Additional context
Here is an example of what Gemini responds with when asking about the Task type, and giving it the link to that document, which has invented a description field and is missing many other fields:

Image

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions