SEP-1938: agencyHint tool annotation #1938
Conversation
…o MCP specification This SEP introduces the `agencyHint` tool annotation to the Model Context Protocol, allowing clients to identify agentic tools that perform complex operations. It provides guidance for tool authors and clients on how to use this new annotation effectively.
|
@LucaButBoring - please take a look when you get a chance. |
LucaButBoring
left a comment
LucaButBoring
left a comment
There was a problem hiding this comment.
Made some small suggestions - the main ones are just to remove the mentions of taskHint, since we turned that into execution.taskSupport just prior to the 11/25 release.
The reference implementation section is also intended to actually link to a draft SDK PR, I don't anticipate that being very difficult for this, though.
|
@000-000-000-000-000 Mind adding me as the assignee on this, since I'm sponsoring it? |
|
Also the PR name should be adjusted to something like |
|
Oh right, and regarding the GHA failure - @thoorp just run |
This is done. Will look into other comments and making the SEP complete. |
LucaButBoring
left a comment
LucaButBoring
left a comment
There was a problem hiding this comment.
Looks good, just left one minor comment - will see about raising this to Core Maintainers (first time sponsoring an SEP so no reliable ETA yet, but I'll relay statuses and give an ETA as soon as I have one).
|
|
||
| Tool authors _should_ set `agencyHint: true` when: | ||
|
|
||
| - The tool encapsulates an internal “agent loop” (e.g., plan–act–observe cycles, tool-chaining, or autonomous retries). |
There was a problem hiding this comment.
nit: I think tool-chaining and autonomous retries are a bit too generic to include in this parenthetical - maybe we should remove the parenthetical entirely and just rely on (or reuse) the semantics described above this to avoid confusion.
|
@localden can we mark this as |
thoorp
changed the title
vinoo999
left a comment
vinoo999
left a comment
There was a problem hiding this comment.
Like the intention of this SEP here. Would be great to see if we can align the review of this with some of the granular features proposed in SEP 1984.
In particular, I think the separation between "agentic" behavior (aiProcessingHint in 1984) and "long running" behavior (slowExecutionHint) are important UX and governance concerns.
I'd be interested in going over specific combination of hints and consistent reproducible UX/governance patterns for the varying hints proposed in 1984 and if that granularity also makes sense to split 1938 into 2 hints (naming aside :) )
|
I think it would be reasonable to remove "long-running" verbiage from the spec around this hint (cc: @thoorp). Agency doesn't necessarily imply something being long-running, and what "long-running" even means is subjective according to the particular host application and server. I'm not sure if I agree a long-running hint is useful just yet, but I'll leave that discussion to #1984. |
|
Yeah, I will update the description to keep the focus on Autonomous / Agentic aspect. |
|
For the "agency" piece on the governance side, #1984 defines the
Do you think these "ai capabilities" can be encapsulated or are separate to an "agency" hint? I think this SEP currently well covers the UX of agency, but not necessarily the governance of tools that can/should be allowed in particular applications. i.e. would like to add in the description that agency implies AI usage explicitly. |
Like the suggestion to include AI usage explicitly. Done. |
4 participants
This PR migrates SEP-1792 (“Add
agencyHinttool annotation”) from the GitHub issue tracker into theseps/directory, following the updated SEP workflow.It adds
seps/0000-agency-hint-tool-annotation.mdin the standard SEP format, documenting the newagencyHintboolean in theToolAnnotationsinterface. The SEP includes sections on motivation, specification, rationale, backward compatibility, reference implementation, and security implications.Original discussion: #1792
Motivation and Context
Agentic tools can perform multi-step operations and require different UX and safety handling compared to simple tools. Adding the
agencyHintannotation will allow clients to identify such tools and apply appropriate confirmation or monitoring flows.How Has This Been Tested?
This is a documentation change only; no executable code is introduced.
Breaking Changes
None. The new annotation is optional and additive. Existing tools and clients are unaffected.
Types of changes
Checklist
Additional context
This PR follows the new SEP process update (Nov 28, 2025) to migrate SEP proposals into pull requests rather than issues.