Proposal: Schema - list-schemas - new protocol element

As originally discussed in:
#358
but now an official proposal.

The MCP protocol is quickly becoming the senses of LLMs. Now that we have both an input and output schema on our tools, we're able to tell the LLM exactly what they can expect from using it.

We can now feel with the tools that we have and grab resources and have structured conversations with prompts. Now we need some way to describe the world. Some way that works across tools and resources within the protocol to describe what we can expect from them. We need to be able to SEE!

The problem is that many tools use the same elements over and over again. If I can only specify the inputSchema and outputSchema to the tool, I end up having to repeat the same data over and over again wasting valuable context.

I propose a new list-schemas RPC command and a Schemas element be added to the central concept of the MCP protocol.

List schemas would return a list of JSON schemas that are named and can be referenced in the tools and resources (and maybe someday other parts of the protocol).

This is quite like the OpenAPI specification itself with it's concept of models.

export interface Schema {
  name: string
  description: string
  schema: {
    type: "object";
    properties?: { [key: string]: object };
    required?: string[];
  }
}

export interface SchemaReference {
  type: "ref/schema";
  /**
   * The name of the schema
   */
  name: string;
}

export interface ListSchemasRequest {}
export interface ListSchemasResponse {
  schemas: Schema[]
}

I posted similar comment in another thread related to this exact proposal, so I'll repost it here:

Really solid proposal. This fills a real gap I've run into, too; we can talk about tools and resources all day, but we don't have a clean way to describe what the world actually looks like to the agent. Schemas give us that missing piece. Two thumbs-up from me on this!

Also related to and improved upon by the adoption of: #611

@yinzara

@yinzara have you considered trying to use Resources for this purpose?

You could have a folder of Resources called schemas (a folder of them so you could pull all them in at once with a Resource uriTemplate), each defining one of these references.

One of these Resources might have a uri like schema://myDTOShape.

Then, in all your tool definitions, you could do things like description=This fetches an object of schema://myDTOShape. To view the full shape, you can use the getSchemaResource tool. That would enable your model to chain tool calls to leverage the schema without it regularly blowing up your context.

This defeats the whole purpose of having inputSchema and/or outputSchema on a tool. If I have to tell the tool some kind of metaschema made up construct, why have inputSchema at all?

I'll concede one potential alternative to my 'list-schemas' proposal is to allow inputSchema and outputSchema to support the $ref syntax as provided by the JSON Schema standard.

https://json-schema.org/understanding-json-schema/structuring

This should allow you to refer to another JSON schema document by reference with some external URL being a potential option.

The only problem I have with that is that when I wanted to actually pass it to the LLM in their tools API, unless they also supported the $ref syntax on their inputSchema (I can tell you no LLM current supports that) I'm kinda SoL.

I wish the inputSchema on a OpenAI API tools resource supported the $ref syntax. LLMs would have to have the ability to retrieve those schemas and use them in their contexts though.... which SHOULD be possible but is probably a pretty big ask.

I know that Google supports retrieving HTTP and HTTPS URLs in Gemini Prompts, why shouldn't it support retrieving HTTP/HTTPS urls for schema resolution too.

Maybe $defs are the answer. Making the list-tools response allow a $defs optional attribute that allows the tools to return the root defs that can be referenced by any tool.
https://json-schema.org/understanding-json-schema/structuring#defs

@yinzara

I've read the thread a couple of times, but I want to make sure I understand what is being proposed @yinzara .

It sounds like your idea is to refactor the Tool MCP Schema specification to use a reference to a JSON Schema for both the inputSchema and outputSchema - e.g. changing these 2 definitions below?

export interface Tool extends BaseMetadata {
  /**
   * A human-readable description of the tool.
   *
   * This can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a "hint" to the model.
   */
  description?: string;

  /**
   * A JSON Schema object defining the expected parameters for the tool.
   */
  inputSchema: {
    type: "object";
    properties?: { [key: string]: object };
    required?: string[];
  };

  /**
   * An optional JSON Schema object defining the structure of the tool's output returned in
   * the structuredContent field of a CallToolResult.
   */
  outputSchema?: {
    type: "object";
    properties?: { [key: string]: object };
    required?: string[];
  };

The only problem I have with that is that when I wanted to actually pass it to the LLM in their tools API, unless they also supported the $ref syntax on their inputSchema (I can tell you no LLM current supports that) I'm kinda SoL.

Yes, this would be down to the Host application to resolve the Input Schema and pass it to the LLM Provider Function/Tool definition API.

There is no equivalent for "Output Schema" - the Host application needs to decide whether or how to pass that to the model as an additional String somewhere in the Context Window.

< There is no equivalent for "Output Schema" - the Host application needs to decide whether or how to pass that to the model as an additional String somewhere in the Context Window.

So why did we improve the MCP protocol to support outputSchema's if the LLMs don't? Arguing we shouldn't improve the protocol because LLMs don't yet support what we do doesn't seem to have affected the outputSchema's adoption.

< There is no equivalent for "Output Schema" - the Host application needs to decide whether or how to pass that to the model as an additional String somewhere in the Context Window.

I'm curious if you'd know, if I wanted to request Anthropic add "$defs" as an optional parameter to the Messages API to enhance the meanings of passed "tools" and support local "$refs" (i.e. { "$ref" : "#/$defs/MySchema" } ) where would I go about requesting that? :-)

I'm curious if OpenAI would have a place I could lobby for it as them adding it would basically force everyone else to.

Maybe the best way is for us to enhance MCP to support it so that the LLMs follow suit :-) like outputSchemas.

< There is no equivalent for "Output Schema" - the Host application needs to decide whether or how to pass that to the model as an additional String somewhere in the Context Window.

So why did we improve the MCP protocol to support outputSchema's if the LLMs don't? Arguing we shouldn't improve the protocol because LLMs don't yet support what we do doesn't seem to have affected the outputSchema's adoption.

The original PR discussions are here:
#356
#371
#559

Currently, the Tool Input Schema is usually passed to the LLM Provider API to produce a Structured Output representing the tool call.

The Output Schema is useful in these cases:

The Host application chooses to append the Output Schema to the existing Tool Description, or inject the Output Schema in to the Context Window another way to indicate the shape of the Tool Call result. This is of limited utility as models don't have an inherent understanding of JSON.
The Host application has been written in advance to intercept the Structured Output and provide some form of filtering/pre-processing before passing the CallToolResult to the LLM - although in this case the Host application has better options for achieving this end IMO.
The Host application uses the LLM to generate on-the-fly executable agent code that handles MCP Call Tools and Result processing.

For most MCP Server developers I would recommend against using Structured Outputs unless they know that their host application will process the JSON properly. (Also, for backward compatibility at the moment this means duplicating the returned content doubling response size).

@yinzara

The only problem I have with that is that when I wanted to actually pass it to the LLM in their tools API, unless they also supported the $ref syntax on their inputSchema (I can tell you no LLM current supports that) I'm kinda SoL.

@yinzara could you please elaborate? IMHO LLMs are very much capable of de-referencing $ref. But I might be wrong.

I'm curious if you'd know, if I wanted to request Anthropic add "$defs" as an optional parameter to the Messages API to enhance the meanings of passed "tools" and support local "$refs" (i.e. { "$ref" : "#/$defs/MySchema" } ) where would I go about requesting that? :-)

You could have a folder of Resources called schemas (a folder of them so you could pull all them in at once with a Resource uriTemplate), each defining one of these references.

IMHO $ref is more specific that $def since it points to a schema, not any arbitrary piece of schema. So it makes sense to use $ref as the value for inputSchema or outputSchema.

So yes. IMHO leveraging resources for schemas is a very solid idea. @tadasant did you test it out?

I'll concede one potential alternative to my 'list-schemas' proposal is to allow inputSchema and outputSchema to support the $ref syntax as provided by the JSON Schema standard.

IMHO an LLM driven client will use resources to resolve $ref anyway.

Anyway I intend to find out if the resource approach works and propose an SEP if it's relevant.

Navigation Menu

Repository navigation

Proposal: Schema - list-schemas - new protocol element #610

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Proposal: Schema - list-schemas - new protocol element #610

Description

Activity

atomicdragonranch commented on May 30, 2025

yinzara commented on May 30, 2025

tadasant commented on Jul 3, 2025

yinzara commented on Jul 3, 2025

evalstate commented on Jul 4, 2025

yinzara commented on Jul 4, 2025

yinzara commented on Jul 4, 2025

evalstate commented on Jul 7, 2025

JMLX42 commented on Sep 24, 2025

aak204 commented on Apr 13, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions