Codify MCP tool name requirements and add title#152
Codify MCP tool name requirements and add title#152DavidMulder0 wants to merge 5 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.
index.bs
Outdated
| <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.
There was a problem hiding this comment.
I think I tend to agree. Since these are basically just JavaScript functions, providing a name might be useful but it doesn't seem mandatory. I think it's unlikely these things will be on display to users too much, similarly to how JavaScript documentation on event handlers isn't really displayed to users when they click buttons and interact with a page.
We could very much be wrong here, so I'm happy to revisit. Since "v0" isn't necessary this "this PR" but it's before things move too far along in final/shipping implementations in browsers, and we have a lot of testing ahead of us, I'm for proceeding with optional title and revisiting if UX feedback is worse because of it.
There was a problem hiding this comment.
I did my best to convince you guys otherwise, but I clearly failed 😅, so I updated the PR to make title optional.
There was a problem hiding this comment.
Honestly, this seems like exactly what our relationship with AAIF is good for, per webmachinelearning/charter#14.
How about we loop in @vthub for thoughts from an MCP perspective? I've also dropped a comment in https://discord.com/channels/1358869848138059966/1416012674663452752/1451622415040905317 to ask folks over there.
|
|
||
| <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?
There was a problem hiding this comment.
Does MCP encourage something similar?
There was a problem hiding this comment.
There is no explicit rule in the spec that says "titles MUST be localized." BUT since those are not passed to the LLM but only for display purposes to the user, it'd make sense to provide them in the browser user language. Thoughts?
There was a problem hiding this comment.
For now added a line to the non-normative ModelContextTool Dictionary section that states 'It is recommended that this string be localized to the user’s language.'
index.bs
Outdated
| <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?)