Encourage title properties/usage for objects/resources likely t… #663

ZachGerman · 2025-06-06T06:20:46Z

Encourage UI-friendly naming by introducing a dedicated optional title property across the specification and updating all related examples to include it.

Added optional title field to resource, tool, prompt, clientInfo, and serverInfo definitions in the spec.
Updated JSON examples to include title entries where they're likely to be used.

Motivation and Context

By introducing title as a dedicated property, we ensure clarity and consistency in how data is surfaced to end users, improving both developer experience and user-facing usability as the protocol evolves.

Breaking Changes

Will users need to update their code or configurations? No. According to the language added to the spec, "if no title is provided, name should be used for display purposes". Thus, implementations currently leveraging name variables for display will be preserved.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

To be added to docs if/when this PR is published to an official spec version:

Naming conventions:

Objects with names expose two distinct properties: name and title. The name is intended for programmatic or logical use, while title is intended for UI and end-user contexts — optimized to be human-readable and easily understood, even by those unfamiliar with domain-specific terminology.

bhosmer-ant · 2025-06-10T04:11:49Z

Hi @ZachGerman - interested in your thoughts on a couple of things, just thinking out loud:

the "just use name if displayName is not provided" is nice for new client / old server compatibility. For old client / new server situations, it will mean tool names might be less readable than previously. I don't think this is a dealbreaker, but wanted to flag it.
wonder if you've thought about when to use displayName vs. annotations.title for tools. We might want to give some guidance about that in the new language.

schema/draft/schema.ts

connor4312

MCP already uses the title for the "displayName" in ToolAnnotations.title. Could we normalize one direction or the other?

connor4312 · 2025-06-10T20:33:49Z

docs/specification/draft/server/tools.mdx

@@ -264,6 +267,7 @@ Example tool with output schema:
 ```json
 {
  "name": "get_weather_data",
+  "displayName": "Weather Data Retriever",


This doesn't appear to be represented in the spec change and is duplicative with existing ToolAnnotations.title

bhosmer-ant · 2025-06-11T16:46:49Z

Hi @ZachGerman - this is definitely a useful addition and we'd like to add it to the draft spec, but with the following changes:

instead of adding displayName as a top-level property, create a BaseMetadata interface that contains name and title (rather than displayName)
for any type that contains name, inherit from that interface instead. (This will give us a place to make further additions later.)
for the documentation (in addition to changing displayName to title globally) we'd want to add language in Tool noting that in addition to the "first title then fall back to name" precedence order you specify elsewhere, for tools it should be "first title then annotations.title then name"

Realize this is a nontrivial set of edits and we're on a fairly tight schedule for the spec release, so if you don't have time/bandwidth in the next day or so we're happy to make the changes. Just LMK!

ZachGerman · 2025-06-11T21:31:51Z

Hi @ZachGerman - this is definitely a useful addition and we'd like to add it to the draft spec, but with the following changes:
* instead of adding `displayName` as a top-level property, create a `BaseMetadata` interface that contains `name` and `title` (rather than `displayName`)

* for any type that contains `name`, inherit from that interface instead. (This will give us a place to make further additions later.)

* for the documentation (in addition to changing `displayName` to `title` globally) we'd want to add language in `Tool` noting that in addition to the "first `title` then fall back to `name`" precedence order you specify elsewhere, for tools it should be "first `title` then `annotations.title` then `name`"
Realize this is a nontrivial set of edits and we're on a fairly tight schedule for the spec release, so if you don't have time/bandwidth in the next day or so we're happy to make the changes. Just LMK!

Done. Please let me know if anything else needs changed. I'm on-call this week, so I won't finish the server transport until next week, but this PR is small enough to keep up with during my on-call.

…epresented in a UI

bhosmer-ant · 2025-06-11T21:40:02Z

Awesome! Will review shortly but also please fix the merge conflicts when you have a chance. Thanks for the quick turnaround!

bhosmer-ant · 2025-06-11T22:38:35Z

Ugh sorry to do this to you but it looks like you need to rerun npm run generate:json 🙏 (also I'm not sure why the PR is still showing "out of date with the base branch" after your merge, but as long as there are no conflicts it should be innocuous)

ZachGerman · 2025-06-11T23:23:30Z

Ugh sorry to do this to you but it looks like you need to rerun npm run generate:json 🙏 (also I'm not sure why the PR is still showing "out of date with the base branch" after your merge, but as long as there are no conflicts it should be innocuous)

Should be fixed now.

bhosmer-ant · 2025-06-12T02:11:23Z

Hi @ZachGerman - had to make one change, Root.name was a different beast than the rest (optional, so making it mandatory would be bc-breaking, and paired with a URI, which arguably can serve as a machine-friendly id). Also it's not in your original list of candidates, so I suspect it might've been an accidental change.

Having pushed the change I can't merge it, but it should go in shortly. Thanks again for doing this!

bhosmer-ant

LGTM!

ihrpr

do we also need to update PromptReference?

ihrpr · 2025-06-12T08:40:52Z

schema/draft/schema.ts

@@ -264,10 +264,29 @@ export interface ServerCapabilities {
 }

 /**
- * Describes the name and version of an MCP implementation.
+ * Base interface for metadata with name and title (display name) properties.


should we hint that name is an identifier?

Suggested change

* Base interface for metadata with name and title (display name) properties.

* Base interface for metadata with name (identifier) and title (display name) properties.

bhosmer-ant · 2025-06-12T15:03:05Z

do we also need to update PromptReference?

yes! thanks for catching

bhosmer-ant · 2025-06-12T15:47:18Z

[edited] back to plan A, will land this as-is + @ihrpr suggestion (I'll push it shortly)

ihrpr

LGTM

ZachGerman mentioned this pull request Jun 6, 2025

spec should define a unique ID for resource templates #566

Open

ZachGerman force-pushed the feature/displayName branch from d7801b2 to 7340d98 Compare June 6, 2025 20:34

dsp-ant added this to Standards Track Jun 9, 2025

dsp-ant moved this to Consulting in Standards Track Jun 9, 2025

dsp-ant added this to the DRAFT 2025-06-XX milestone Jun 9, 2025

dsp-ant reviewed Jun 10, 2025

View reviewed changes

schema/draft/schema.ts Show resolved Hide resolved

dsp-ant moved this from Consulting to In Review in Standards Track Jun 10, 2025

connor4312 reviewed Jun 10, 2025

View reviewed changes

ZachGerman force-pushed the feature/displayName branch 2 times, most recently from 6b634a1 to f00ada8 Compare June 11, 2025 21:29

Encourage title properties/usage for objects/resources likely to be r…

1c54a77

…epresented in a UI

ZachGerman force-pushed the 8000 feature/displayName branch from f00ada8 to 1c54a77 Compare June 11, 2025 21:36

ZachGerman changed the title ~~Encourage displayName properties/usage for objects/resources likely t…~~ Encourage title properties/usage for objects/resources likely t… Jun 11, 2025

Merge branch 'main' into feature/displayName

9d1374a

ZachGerman and others added 2 commits June 11, 2025 15:48

Merge branch 'modelcontextprotocol:main' into feature/displayName

bdcb021

Minor wording change

5bf5457

bhosmer-ant added 2 commits June 11, 2025 22:05

revert Root

9a96c28

Merge branch 'main' into feature/displayName

ffd8e6c

bhosmer-ant enabled auto-merge June 12, 2025 02:07

bhosmer-ant self-requested a review June 12, 2025 02:16

bhosmer-ant previously approved these changes Jun 12, 2025

View reviewed changes

ihrpr reviewed Jun 12, 2025

View reviewed changes

update PromptReference, add identifier language

694876e

bhosmer-ant dismissed their stale review via 694876e June 12, 2025 22:13

Merge branch 'main' into feature/displayName

78ec9ba

bhosmer-ant requested review from dsp-ant and ihrpr June 12, 2025 22:14

ihrpr approved these changes Jun 13, 2025

View reviewed changes

bhosmer-ant merged commit 8719898 into modelcontextprotocol:main Jun 13, 2025

github-project-automation bot moved this from In Review to Approved in Standards Track Jun 13, 2025

ihrpr mentioned this pull request Jun 13, 2025

Encourage title properties/usage for objects/resources likely #731

Open

felixweinberger mentioned this pull request Jun 17, 2025

Add title to tools, resources, prompts modelcontextprotocol/python-sdk#972

Merged

9 tasks

ihrpr mentioned this pull request Jun 17, 2025

changelog additions #768

Merged

primeinc mentioned this pull request Jun 18, 2025

Migrate from fastmcp to official modelcontextprotocol/python-sdk primeinc/telnyx-mcp-server#13

Draft

wommel0 mentioned this pull request Jun 19, 2025

Add title field for human-friendly display names, so that name can be used as a programmatic identifier abap-ai/mcp#50

Closed

connor4312 mentioned this pull request Jun 20, 2025

fix: deduplicate title definition in tools #813

Open

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Encourage title properties/usage for objects/resources likely t… #663

Encourage title properties/usage for objects/resources likely t… #663

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

	* Base interface for metadata with name and title (display name) properties.
	* Base interface for metadata with name (identifier) and title (display name) properties.

Encourage title properties/usage for objects/resources likely t… #663

Encourage title properties/usage for objects/resources likely t… #663

Conversation

Uh oh!

Motivation and Context

Breaking Changes

Types of changes

Checklist

To be added to docs if/when this PR is published to an official spec version:

Naming conventions:

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!