Codify MCP tool name requirements and add title#152
Codify MCP tool name requirements and add title#152DavidMulder0 wants to merge 3 commits intowebmachinelearning:mainfrom
Conversation
Co-authored-by: Dominic Farolino <domfarolino@gmail.com>
|
First of all: Apologies for wasting your time and thank you for being kind about it. Sincerely hope I did better this time 😅. Anyway, I included the checks in the |
domfarolino
left a comment
domfarolino
left a comment
There was a problem hiding this comment.
Don't sweat it, specs are hard! Thanks for the contribution.
| <xmp class="idl"> | ||
| dictionary ModelContextTool { | ||
| required DOMString name; | ||
| required DOMString title; |
There was a problem hiding this comment.
I'm still a little iffy on this. In #133 (comment) you justified this by saying actual MCP made this optional specifically for backwards compatibility, implying that if they could, they'd make it mandatory. But is that definitely true? Is MCP not versioned in any way? Maybe it's not and it has to evolve just like the web platform, in which case we can make this mandatory without the compat risk since we haven't shipped yet.
On the other hand, I can also see why title would be optional, since it isn't strictly required to make the tool useful. Plus it does feel funny to deviate from MCP requirements just because we showed up later and have no compat risk.
There was a problem hiding this comment.
There was a problem hiding this comment.
Some useful information and some thoughts:
First of all, you're correct, MCP does support versioning, but they seem to care a lot about backwards compatibility regardless (I think none of their releases have been backwards compatibility breaking as of yet). Here are the relevant PRs:
- ToolAnnotations modelcontextprotocol/modelcontextprotocol#185
introducestool.annotations.title - Encourage title properties/usage for objects/resources likely t… modelcontextprotocol/modelcontextprotocol#663
introducestool.title, explicity notes thattool.title->tool.annotations.title->tool.nameis the order of preference - fix: deduplicate title definition in tools modelcontextprotocol/modelcontextprotocol#813
open PR that suggests removingtool.annotations.title, but is kept open due to backwards compatibility concerns awaiting an MCP release that will be backwards incompatible
The big question is how the UI is going to look. Most - but not all - agentic UIs I have seen will refer to tools and visualize tool calls in some way (typically to give a sense of what's going on and/or to get approval from the Human and/or to give the Human control over which tools the agent has access to). If title is not required then browsers are likely to fall back on name, which simply isn't meant for human consumption (especially with the character restrictions outlined here, and additionally I presume name will typically not be localized to the user's language). MCP's original target audience was very much developers who don't mind seeing deleteNodeTool, but that target audience is shifting especially with WebMCP.
There is I think also a risk where different browsers will implement different UIs, and thus a developer using a browser that shows 'tool.title' less prominently (or not at all) might just leave it empty. Making it required would give a guaranteed set of information to browser implementors.
And lastly: anything that's required in v1 can be made optional in v2, but anything that's optional in v1 will have to be optional forever 😅.
There was a problem hiding this comment.
tool.annotations.title seems out of the equation. Thanks for sharing links!
Now, the question is should we make it tool.title optional or not? Having played with a lot of WebMCP demos lately, I'm not convinced yet a mandatory title would actually help users since some of them tend to be opaque things that are there to help the agent, not necessarily the user in their quest.
I also feel like the agent can come up with a better wording when invoking those, and presenting them to the user given they have more context.
For this reason, I'd lean towards making it optional. Note that this a not a strong objection.
|
|
||
| <dt><code><var ignore>tool</var>["{{ModelContextTool/title}}"]</code></dt> | ||
| <dd> | ||
| <p>A label for the tool. This is used by the user agent to reference the tool in the user interface. |
There was a problem hiding this comment.
Regarding internationalization: should we add a note advising developers to localize the title based on the user's language settings?
| <xmp class="idl"> | ||
| dictionary ModelContextTool { | ||
| required DOMString name; | ||
| required DOMString title; |
There was a problem hiding this comment.
tool.annotations.title seems out of the equation. Thanks for sharing links!
Now, the question is should we make it tool.title optional or not? Having played with a lot of WebMCP demos lately, I'm not convinced yet a mandatory title would actually help users since some of them tend to be opaque things that are there to help the agent, not necessarily the user in their quest.
I also feel like the agent can come up with a better wording when invoking those, and presenting them to the user given they have more context.
For this reason, I'd lean towards making it optional. Note that this a not a strong objection.
3 participants
Addressing #145 and #133 .
(Related topic: some guidance regarding localization would be great.
namedoes not have to be localized presumably (it won't be shown to the user presumably).titlemay be localized. Willdescriptionbe shown to the end user? From personal experience I am treating that as a solid 'no' (all MCP descriptions I have written so far were 'prompt engineered'). Lastly I have seen the tool arguments get presented to the user relatively often, so should there be a way to localize the display of those?)