Make the tool properties actual JSON Schema objects

[redox]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

While the inputSchema of a tool expects a JSON Schema object - the specification is not clear about whether this applies to the underlying properties.

In most examples you read online, it looks like it is as most of them are in the form

properties: {
   a: { type: "number" },
   b: { type: "string" }
},

But in the TS code, it's simply:

/**
 * Definition for a tool the client can call.
 */
export interface Tool {
  /**
   * The name of the tool.
   */
  name: string;
  /**
   * A human-readable description of the tool.
   */
  description?: string;
  /**
   * A JSON Schema object defining the expected parameters for the tool.
   */
  inputSchema: {
    type: "object";
    properties?: { [key: string]: object }; // <===========
    required?: string[];
  };
}

and in the schema.json it's similar:

                        "properties": {
                            "additionalProperties": {
                                "additionalProperties": true,
                                "properties": {},
                                "type": "object"
                            },
                            "type": "object"
                        },

Yet, the "official" inspector suggests that properties are also following the JSON Schema for its properties:

export type JsonSchemaType = {
  type: "string" | "number" | "integer" | "boolean" | "array" | "object";
  description?: string;
  properties?: Record<string, JsonSchemaType>;
  items?: JsonSchemaType;
};

There are a few great features coming with the entire support of JSON Schema for properties, including support enumerated values (as I initially tried to implemented in modelcontextprotocol/inspector#196) but also defined formats which could be very convenient to use.

I would love to hear from others how this sounds and whether I'm missing something.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[atesgoral]

@redox properties are already the properties of a top-level object defined in JSON Schema. It's JSON Schema all the way down. It's implicit. But this could be further clarified by including at least one example that demonstrates a complex property that uses additional JSON Schema features.

[redox]

Great to hear! Making this explicit would be lovely then, so we can implement support of enum and format in client & servers - as I tried to do in modelcontextprotocol/inspector#196.

[samsp-msft]

The results of a tool are defined to be text or binary together with a mime type. If the resulting output is structured such as JSON or xml, it seems like there should be a way for the tool definition (and potentially resources too) to have an annotation that describes the schema of the resulting data.

The reason for adding the schema is to be able to give the extra annotations on what each field in the data represents - and using the schema as an existing/well-known format seems sensible.

While it could have a schema URL embedded in the data payload, that would mean that the client would have to fetch the schema which it may not always be feasible, it may be proprietary for that MCP server and they don't want to make it public. I don't think you would want to embed the schema data on every result either, as that could be duplicative and potentially exhaustive.

[cliffhall]

I don't think you would want to embed the schema data on every result either, as that could be duplicative and potentially exhaustive.

Tool requests have a schema. It's just down to whether a string type property can have an optional enum list or format. In the modelcontextprotocol/inspector#196 enum PR, it looks like this:

I think this is an easy thing to support and it will be valuable to the LLM that is calling the tool.

If a string field should only have values "red", "green", or "blue" then specify that or the LLM can choose to send in "orange".

Same with format. If it is an email address, a date, or a URI, telling the LLM what a valid input in that field looks like with a JSON format field is precise, while the description of the field is a weak way to specify what we want.