Proposal: Shared Input Schema Fragments for WebMCP Tool Definitions

[InspectorAB]

Problem

In WebMCP applications that expose multiple tools, it is common for different tools to use the same conceptual parameters (for example taskId, userId, sessionId, etc.).

Currently, each tool defines its own inputSchema. This means the same parameter may be defined multiple times across tools.

Example (Current Pattern)

navigator.modelContext.registerTool({
name: "getTask",
description: "Retrieve a task",
inputSchema: {
type: "object",
properties: {
taskId: { type: "string", description: "Task identifier" }
}
}
});

navigator.modelContext.registerTool({
name: "updateTask",
description: "Update a task",
inputSchema: {
type: "object",
properties: {
taskId: { type: "string" }
}
}
});

Over time this can lead to:

• inconsistent parameter definitions across tools
• slightly different schemas for the same concept

Proposed Idea

Introduce a mechanism that allows developers to define shared schema fragments which can be reused across multiple WebMCP tools.

Example concept:

navigator.modelContext.defineSchema({
taskId: {
type: "string",
description: "The task identifier"
},
userId: {
type: "string",
format: "uuid"
}
});

Tools could then reference these shared fragments when defining their inputSchema.

Example:

navigator.modelContext.registerTool({
name: "getTask",
description: "Retrieve a task",
inputSchema: {
type: "object",
properties: {
taskId: "$schema:taskId",
userId: "$schema:userId"
}
}
});

Benefits

• Helps maintain consistent parameter definitions across tools
• Makes large WebMCP tool sets easier to maintain
• Provides clearer and more consistent input contracts for agents interacting with tools

Discussion

JSON Schema already supports $ref, but WebMCP tool schemas are often defined inline in JavaScript. Managing shared schema fragments across multiple tools can therefore become inconsistent as application grows. Shared schema fragments could help maintain consistent input contracts across tools and improve agent interoperability by ensuring common parameters follow canonical definitions.

Would a mechanism for shared schema fragments in WebMCP tool definitions be useful for maintaining consistent parameter definitions across tools, or is this better handled outside the core API?