Repository navigation
Description
Preamble
Title: Support default values for all primitive types in elicitation schemas
Author: Tapan Chugh ([email protected])
Status: Accepted
Type: Standards Track
Created: 2025-07-22
Accepted: 2025-08-22
Abstract
This SEP recommends adding support for default values to all primitive types in the MCP elicitation schema (StringSchema, NumberSchema, and EnumSchema), extending the existing support that only covers BooleanSchema.
Motivation
Elicitations in MCP offer a way to mitigate complex API designs: tools can request information on-demand rather than resorting to convoluted parameter handling. The challenge however is that users must manually enter obvious information that could be pre-populated for more natural interactions. Currently, only BooleanSchema supports default values in elicitation requests. This limitation prevents servers from providing sensible defaults for text inputs, numbers, and enum selections leading to more user overhead.
Real-World Example
Consider implementing an email reply function. Without elicitation, the tool becomes unwieldy:
def reply_to_email_thread(
thread_id: str,
content: str,
recipient_list: List[str] = [],
cc_list: List[str] = []
) -> None:
# Ambiguity: Does empty list mean "no recipients" or "use defaults"?
# Complex logic needed to handle different combinationsWith elicitation, the tool signature itself can be much simpler
def reply_to_email_thread(
thread_id: str,
content: Optional[str] = ""
) -> None:
# Code can lookup the participants from the original thread
# and prepare an elicitation request with the defaults setupconst response = await client.request("elicitation/create", {
message: "Configure email reply",
requestedSchema: {
type: "object",
properties: {
recipients: {
type: "string",
title: "Recipients",
default: "[email protected], [email protected]" // Pre-filled
},
cc: {
type: "string",
title: "CC",
default: "[email protected]" // Pre-filled
},
content: {
type: "string",
title: "Message"
default: "" // If provided in the tool above
}
}
}
});Implementation
A working implementation demonstrating clients require minimal changes to display defaults (~10 lines of code):
- Implementation PR: Demonstrate feasibility of default values in elicitation flows chughtapan/fast-agent#2
- A demo with the above email reply workflow: https://asciinema.org/a/X7aQZjT2B5jVwn9dJ9sqQVkOM
Specification
Schema Changes
Extend the elicitation primitive schemas to include optional default values:
export interface StringSchema {
type: "string";
title?: string;
description?: string;
minLength?: number;
maxLength?: number;
format?: "email" | "uri" | "date" | "date-time";
default?: string; // NEW
}
export interface NumberSchema {
type: "number" | "integer";
title?: string;
description?: string;
minimum?: number;
maximum?: number;
default?: number; // NEW
}
export interface EnumSchema {
type: "string";
title?: string;
description?: string;
enum: string[];
enumNames?: string[];
default?: string; // NEW - must be one of enum values
}
// BooleanSchema already has default?: booleanBehavior
- The
defaultfield is optional, maintaining full backward compatibility - Default values must match the schema type
- For EnumSchema, the default must be one of the valid enum values
- Clients that support defaults SHOULD pre-populate form fields. Clients that don't support defaults MAY ignore the field entirely.
Rationale
- The high-level rationale is to follow the precedent set by BooleanSchema rather than creating new mechanisms.
- Making defaults optional ensures backward compatibility.
- This maintains the high-level intuition of keeping the client implementation simple.
Alternatives Considered
- Server-side Templates: Servers could maintain templates separately, but this adds complexity
- New Request Type: A separate request type for forms with defaults would fragment the API
- Required Defaults: Making defaults required would break existing implementations
Backwards Compatibility
This change is fully backward compatible with no breaking changes. Clients that don't understand defaults will ignore them, and existing elicitation requests continue to work unchanged. Clients can adopt default support at their own pace
Security Implications
No new security concerns:
- No Sensitive Data: The existing guidance against requesting sensitive information still applies
- Client Control: Clients retain full control over what data is sent to servers
- User Visibility: Default values are visible to users who can modify them before submission
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsFinal
- StatusShow more project fieldsIn progress
Activity
[-]SEP: Support default values for all primitive types in elicitation schemas[/-][+]SEP 1034 : Support default values for all primitive types in elicitation schemas[/+][-]SEP 1034 : Support default values for all primitive types in elicitation schemas[/-][+]SEP-1034 : Support default values for all primitive types in elicitation schemas[/+]pcarleton commentedon Aug 15, 2025
Thanks for the great demo showing how it can be used.
I can see this being useful for
writetools that want to allow final edits before the user hits send, e.g. the full "content" could be pre-filled, and the user could edit it first. It can be annoying otherwise if you get a "accept/decline" elicitation, and you have to say "no" and try to get the model to fix the arguments.chughtapan commentedon Aug 15, 2025
Thanks @pcarleton
I agree - a great place to showcase this with a git commit tool. The model gets the commit message mostly correct, but I always want to refine it a bit. I've been thinking that the git reference server might be the perfect place to showcase the UX improvements here and in #1330.
cliffhall commentedon Sep 1, 2025
Closing as this SEP was accepted and its implementation merged:
#1035 (review)
feat: Add SDK support for SEP-1034 default values in elicitation schemas
dend commentedon Nov 12, 2025
Linked to #1035
Support client-side elicitation with SEP-1034 schema defaults