Skip to content

Conversation

@sambhav
Copy link
Member

@sambhav sambhav commented Dec 15, 2025

This PR introduces a SEP proposing six new tool annotations: aiProcessingHint, slowExecutionHint, resourceIntensiveHint, sensitiveDataHint, privilegedAccessHint, and reversibleHint.

Motivation and Context

Organizations implementing MCP need better metadata about tools to support governance policies, security controls, and user experience enhancements. The current tool annotations are limited to basic operation semantics and don't provide sufficient information for:

  • Governance & Compliance: Identifying AI-enabled tools that may require special policies
  • Security: Distinguishing tools that access sensitive data or require elevated privileges
  • Resource Management: Managing system resources for intensive or long-running operations
  • User Experience: Providing appropriate warnings, progress indicators, and categorization

This SEP formalizes the proposal from #616 and follows similar patterns established in #1938.

How Has This Been Tested?

Breaking Changes

None. All new annotations are optional with undefined as the default, maintaining full backward compatibility.

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

Additional context

Key Design Decisions

  • Three-state semantics: undefined (no claim made), false (explicitly not applicable), true (explicitly applicable)
  • Hints only: All annotations are advisory—clients MUST NOT make security-critical decisions based solely on annotations
  • Includes guidance for both tool authors and clients on when/how to use each annotation

New Annotations

Annotation Purpose
aiProcessingHint Identifies AI/LLM processing for governance policies
slowExecutionHint Indicates long-running tools for progress UI/timeouts
resourceIntensiveHint Marks resource-heavy tools for scheduling
sensitiveDataHint Flags sensitive data access for audit logging
privilegedAccessHint Requires elevated permissions for security warnings
reversibleHint Operations can be undone for user confidence

@sambhav sambhav force-pushed the sep-comprehensive-tool-annotations branch 3 times, most recently from e984577 to 777137c Compare December 15, 2025 22:56
@sambhav sambhav changed the title SEP: Comprehensive Tool Annotations for Enhanced Governance and UX SEP-1984: Comprehensive Tool Annotations for Enhanced Governance and UX Dec 15, 2025
@sambhav sambhav force-pushed the sep-comprehensive-tool-annotations branch 2 times, most recently from ece9706 to b90e4a9 Compare December 15, 2025 22:58
@sambhav sambhav force-pushed the sep-comprehensive-tool-annotations branch 2 times, most recently from 1ac8d33 to ed93f3c Compare December 15, 2025 23:13
@sambhav sambhav added proposal SEP proposal without a sponsor. SEP labels Dec 15, 2025
@pwwpche
Copy link
Contributor

pwwpche commented Dec 17, 2025

A good tool hint leads to consistent and unambiguous client/server behaviors. Like idempotentHint clearly indicates to client that "this tool can be retried without side effects on the world state". However in this proposal, many hints are not "clearly, unambiguously actionable". Client could implement very different behaviors on the same hint from the server, leading to inconsistency.

Also some of the hints could be substituted by existing MCP mechanisms:

  • slowExecutionHint - This should be implemented as a Task
  • privilegedAccessHint - A proper way is to use out of band elicitation to acquire auth info.
  • reversibleHint: Reverting is usually harder to implement and error prone. A better design pattern is to implement a tool with idempotentHint, so that client could retry when failure. This is often more robust than asking client to revert.

@vinoo999
Copy link

vinoo999 commented Dec 17, 2025

A good tool hint leads to consistent and unambiguous client/server behaviors. Like idempotentHint clearly indicates to client that "this tool can be retried without side effects on the world state". However in this proposal, many hints are not "clearly, unambiguously actionable". Client could implement very different behaviors on the same hint from the server, leading to inconsistency.

@pwwpche fair point, is there an established process to make "hints" / trial hints in a structured manner to establish whether the UX and Governance around it is consistent? Would be nice if we had an extension/hint-test-bed for adoption. Also if hints should be all independent seps or not.

Also some of the hints could be substituted by existing MCP mechanisms:

  • slowExecutionHint - This should be implemented as a Task

I think long running and Task semantics can be independent from one another. This is different than the TaskHint originally proposed in #1938 and is more towards UX of long running operations. I think this will especially come into play with the stateless transport work.

  • privilegedAccessHint - A proper way is to use out of band elicitation to acquire auth info.

This is intended to manage governance around this: what are the tools in this chain that CAN access privileged data. Even if we can guarantee auth around this, how do we have auditability.

@sambhav sambhav force-pushed the sep-comprehensive-tool-annotations branch from a0d40eb to 1a801a9 Compare December 18, 2025 00:36
@LucaButBoring
Copy link
Contributor

I think long running and Task semantics can be independent from one another. This is different than the TaskHint originally proposed in #1938 and is more towards UX of long running operations. I think this will especially come into play with the stateless transport work.

Can you elaborate on this a bit more? Transports generally wouldn't be able to leverage hints at all, and the host application already knows which transports each server is using.

@vinoo999
Copy link

I think long running and Task semantics can be independent from one another. This is different than the TaskHint originally proposed in #1938 and is more towards UX of long running operations. I think this will especially come into play with the stateless transport work.

Can you elaborate on this a bit more? Transports generally wouldn't be able to leverage hints at all, and the host application already knows which transports each server is using.

Yeah, do not intend this to be used for transports. I meant that Task-implementing servers may not be long running operations but simply enable reconnects, multiple task/result retrieval. The hint however can be used to establish consistent UX. Additionally for server/receivers that do not implement tasks capabilities, they can still expose slowProcessing hints for appropriate UX.

Couple scenarios for when this hint is useful with and without task capability support.

  1. A server with Task capability need not be slow
  • Ex. A deep research vs quick research answer tool both may generate a report and implement task capability (enabling async-fetch of its output) but one is clearly slowExecution and one is fast (a Fast mode may choose to select only tools that are slowExecution: false while Thinking mode can enable all tools). Implementing Task will not give you information sufficient to make these UX decisions. In both cases, I may fetch this reposrt asynchronously or multiple times from task/result.
  1. A server without Task capability may be slow
  • Ex. In the case of slow tools that are not implementing tasks I would like to use notifications for updating a progress bar in my application rather than being fully async.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

proposal SEP proposal without a sponsor. SEP

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants