Repository navigation
_meta Property on CallToolResult Use is Unclear #264
Description
Activity
Similar to the above, I had a question if it was allowed by the spec to add additional metadata to the
Toolobject referenced inListToolResults. In this case I wish to do annotate the tools with the required scopes in the backing APIs:{ "name": "formManager", "description": "A tool for managing form submissions and templates", "inputSchema": { "type": "object", "properties": { "formId": { "type": "string", "description": "The unique identifier for the form" }, "action": { "type": "string", "description": "The action to perform on the form (create, read, update)" }, "formData": { "type": "object", "description": "The data to be used when creating or updating a form" } }, "required": ["formId", "action"] }, "_meta": { "requiredScopes": [ "read:forms", "create:forms", "update:forms" ] } }Since there is no
additionalPropertieson the root ofTool, it's unclear if this is allowed by the specification.The documentation on _meta indicates that clients and servers may use it to "attach additional metadata to their interactions."
It says certain key names are reserved by the protocol but otherwise, valid
_metakey names have two segments: an optional prefix, and a name then goes on to explain how those are constructed. This all seems pretty clear to me.
Reacted by Tadas AntanaviciusI agree with @cliffhall about the intent here, but I also agree with the issue at hand that
reservedas a term is used differently in close proximity:
I think the first instance should be clarified with simpler language like
The _meta property/parameter allows clients and servers to attach additional metadata to their interactions.Reacted by Cliff HallMaybe a broader question on how we use
_metagoing forward: I see the schema currently hasprogressTokenas a reserved keyword with a specific type.Lets say an MCP uses some new key like 'myCoolKey'. But then later the MCP spec defines something at 'myCoolKey'. Won't this cause issues? If this is the case I can't really see how MCP servers can safely use keys in this namespace.
I think I like the thing that the bit about the modelcontextprotocol/mcp prefix seems to be pointing at, which is official spec things will be namespaced, and everything else will be free for arbitrary metadata. And maybe that means we should move
progressTokento something likemodelcontextprotocol.io/progressToken?Maybe a broader question on how we use
_metagoing forward: I see the schema currently hasprogressTokenas a reserved keyword with a specific type.Lets say an MCP uses some new key like 'myCoolKey'. But then later the MCP spec defines something at 'myCoolKey'. Won't this cause issues? If this is the case I can't really see how MCP servers can safely use keys in this namespace.
I think I like the thing that the bit about the modelcontextprotocol/mcp prefix seems to be pointing at, which is official spec things will be namespaced, and everything else will be free for arbitrary metadata. And maybe that means we should move
progressTokento something likemodelcontextprotocol.io/progressToken?Good callout on the
progressTokenit should absolutely be something likemcp/progressTokenbased on the spec language. That can't happen without a breaking change, so it would be more straightforward to amend the spec to say something like "in addition the reserved key 'progressToken', all keys beginning with ... are reserved."Reacted by adam jonesReacted by adam jones- added a commit that references this issue
on Aug 29, 2025 Closing as resolved by the
2026-07-28release. TheMetaObjectrework defines_metaas a field "which clients and servers use to attach additional metadata to their interactions"."Reserved" is no longer a blanket statement about the whole field: it now applies only to enumerated keys (e.g.,
progressToken) and the reserved key prefixes (io.modelcontextprotocol/,*.mcp/), which also resolves theprogressTokencollision concern raised in the thread. The_metasection of the2026-07-28basic spec matches.If anything is still ambiguous against the released text, please open a fresh issue against the current spec.
Describe the bug
The _meta property on CallToolResult has the description "This result property is reserved by the protocol to allow clients and servers to attach additional metadata to their responses." - "reserved" is generally used in specs to imply that the spec is reserving this for future definition, but I don't think that's actually correct here, I think this is meant as a free form field. The question would be - is that "reserved" in the traditional sense or is it fine to start using this today?
To Reproduce
N/A
Expected behavior
I would clarify the description to say "The result property is available for server to client communication of arbitrary data which falls outside the scope of this specification"
Logs
N/A
Additional context
N/A