feat: Add comprehensive tool annotations for enhanced governance and UX #616
Conversation
This commit introduces a comprehensive set of tool annotations to the Model Context Protocol,
providing rich metadata for better tool management, governance, and user experience.
## What's Added
### New Tool Annotations (6 new boolean hints):
- `aiProcessingHint`: Identifies tools that use AI/LLM processing for governance policies
- `slowExecutionHint`: Indicates long-running tools for better UX and timeout management
- `resourceIntensiveHint`: Marks CPU/memory/disk intensive tools for resource management
- `sensitiveDataHint`: Flags tools that handle confidential information for security controls
- `privilegedAccessHint`: Identifies tools requiring elevated system permissions
- `reversibleHint`: Indicates if tool operations can be undone
### Enhanced Existing Annotations:
- Improved documentation and examples for `readOnlyHint`, `destructiveHint`, `idempotentHint`
- Clarified `openWorldHint` definition to distinguish external vs. controlled environments
- Added comprehensive JSDoc documentation with practical examples
## Why This Is Needed
### Governance & Compliance
- Organizations need to identify AI-enabled tools for governance policies
- Security teams require visibility into privileged and sensitive data operations
- Compliance frameworks often require tracking of destructive vs. reversible operations
### User Experience
- Clients can show appropriate progress indicators for slow/resource-intensive tools
- Users get better warnings and confirmations for destructive or sensitive operations
- Tool categorization enables better organization and presentation in UIs
### Resource Management
- System administrators can limit concurrent execution of resource-heavy tools
- Clients can implement intelligent scheduling and queuing based on resource requirements
- Better timeout and retry logic based on execution characteristics
## Files Changed
### Schema Updates:
- `schema/draft/schema.ts`: Added comprehensive ToolAnnotations with JSDoc
- `schema/2025-03-26/schema.ts`: Updated to match draft schema
- `schema/*/schema.json`: Regenerated from TypeScript definitions
### Documentation:
- `docs/docs/concepts/tools.mdx`: Enhanced with detailed examples and use cases
- `docs/specification/draft/server/tools.mdx`: Added complete Tool Annotations section
## Implementation Notes
- All annotations are **hints** and should not be relied upon for security decisions
- Maintains backward compatibility - all new annotations are optional
- Follows existing MCP patterns with boolean flags and sensible defaults
- Removed redundant annotations identified during design review
## Examples
```json
{
"name": "ai_code_analyzer",
"description": "Analyze code quality using AI",
"inputSchema": { ... },
"annotations": {
"title": "AI Code Analyzer",
"readOnlyHint": true,
"aiProcessingHint": true,
"slowExecutionHint": true,
"sensitiveDataHint": true,
"openWorldHint": true
}
}
```
This enhancement provides the foundation for more sophisticated tool management,
governance compliance, and improved user experiences across MCP implementations.
| | `aiProcessingHint` | boolean | false | If true, the tool involves AI or LLM processing | | ||
| | `slowExecutionHint` | boolean | false | If true, the tool typically takes a long time to execute | | ||
| | `resourceIntensiveHint` | boolean | false | If true, the tool is resource-intensive (CPU, memory, or disk) | | ||
| | `sensitiveDataHint` | boolean | false | If true, the tool processes or has access to sensitive data | |
There was a problem hiding this comment.
@SamMorrowDrums has done some thinking here recently
There was a problem hiding this comment.
I have, and my proposal is to add annotations to tool responses. Many tools can access sensitive data, however whether they did or not in a specific call depends on the params passed to it, so I was looking for ways to flag to the host application that now there is sensitive data in the context, to behave differently.
I will still share my proposal once ready because it solves slightly different problems to this one.
|
This all looks like useful metadata, however I think that these should be covered either with the upcoming |
|
Been working on a similar idea here: #622 I like the key design decisions, specifically "Hints only". It would be up to both the user and the client to respect this. The main difference is informative vs requesting a specific paradigm (isolation). A |
|
I finally put up request/response annotations proposal that @connor4312 mentioned I had been exploring #711 |
dsp-ant
left a comment
dsp-ant
left a comment
There was a problem hiding this comment.
I think this will require a SEP.
|
|
||
| /** | ||
| * If true, this tool involves AI or LLM processing. | ||
| * | ||
| * This includes any tool that uses machine learning models, | ||
| * language models, or AI services for processing data or | ||
| * generating responses. | ||
| * | ||
| * Examples: | ||
| * - aiProcessingHint: true → generate_text, analyze_sentiment, create_embedding | ||
| * - aiProcessingHint: false → database_query, file_upload, send_email | ||
| * | ||
| * Default: false | ||
| */ | ||
| aiProcessingHint?: boolean; | ||
|
|
||
| /** | ||
| * If true, this tool typically takes a long time to execute. | ||
| * | ||
| * This helps clients decide whether to show progress indicators, | ||
| * set appropriate timeouts, or warn users about expected delays. | ||
| * | ||
| * Examples: | ||
| * - slowExecutionHint: true → large_file_processing, model_training, video_encoding | ||
| * - slowExecutionHint: false → simple_calculation, cache_lookup, status_check | ||
| * | ||
| * Default: false | ||
| */ | ||
| slowExecutionHint?: boolean; | ||
|
|
||
| /** | ||
| * If true, this tool is resource-intensive (CPU, memory, or disk). | ||
| * | ||
| * This helps clients manage system resources and potentially | ||
| * limit concurrent executions of resource-heavy tools. | ||
| * | ||
| * Examples: | ||
| * - resourceIntensiveHint: true → image_processing, data_compression, crypto_mining | ||
| * - resourceIntensiveHint: false → text_formatting, simple_math, configuration_read | ||
| * | ||
| * Default: false | ||
| */ | ||
| resourceIntensiveHint?: boolean; | ||
|
|
||
| /** | ||
| * If true, this tool processes or has access to sensitive data. | ||
| * | ||
| * This includes personally identifiable information (PII), | ||
| * credentials, financial data, or any confidential information | ||
| * that requires special handling or governance. | ||
| * | ||
| * Examples: | ||
| * - sensitiveDataHint: true → access_user_passwords, read_financial_records, process_medical_data | ||
| * - sensitiveDataHint: false → get_weather, public_api_lookup, system_time | ||
| * | ||
| * Default: false | ||
| */ | ||
| sensitiveDataHint?: boolean; | ||
|
|
||
| /** | ||
| * If true, this tool requires elevated system privileges to execute. | ||
| * | ||
| * This indicates that the tool needs administrative, root, or | ||
| * special permissions that go beyond normal user-level access. | ||
| * | ||
| * Examples: | ||
| * - privilegedAccessHint: true → install_software, modify_system_config, restart_service | ||
| * - privilegedAccessHint: false → read_user_file, send_http_request, calculate_hash | ||
| * | ||
| * Default: false | ||
| */ | ||
| privilegedAccessHint?: boolean; | ||
|
|
||
| /** | ||
| * If true, this tool's operations can be undone or reversed. | ||
| * | ||
| * This annotation is only meaningful when readOnlyHint is false. | ||
| * Reversible operations provide some mechanism to undo their effects. | ||
| * | ||
| * Examples: | ||
| * - reversibleHint: true → create_backup (can be deleted), rename_file (can rename back) | ||
| * - reversibleHint: false → send_email (cannot unsend), delete_permanently | ||
| * | ||
| * Default: false | ||
| */ | ||
| reversibleHint?: boolean; |
There was a problem hiding this comment.
These would require a SEP.
I think the general question here is about the taxonomy of hints.
| | `openWorldHint` | boolean | true | If true, the tool may interact with an "open world" of external entities | | ||
| | `aiProcessingHint` | boolean | false | If true, the tool involves AI or LLM processing | | ||
| | `slowExecutionHint` | boolean | false | If true, the tool typically takes a long time to execute | | ||
| | `resourceIntensiveHint` | boolean | false | If true, the tool is resource-intensive (CPU, memory, or disk) | |
There was a problem hiding this comment.
That might generalize to a sense of cost?
| * | ||
| * Default: false | ||
| */ | ||
| sensitiveDataHint?: boolean; |
There was a problem hiding this comment.
This probably applies to resources as well.
|
This change would now require an SEP. Your summary says "These annotations enable better governance policies, security controls, resource management, and user experience enhancements", but it's not clear to me exactly how a client would behave differently when presented with these annotations, so you may want to discuss that in your Rationale. Also, depending on how specialized a client must be to benefit from these annotations, there is an argument for implementing them as (unofficial) fields in |
|
@sambhav Did this ever become a SEP? Shall we close this PR out? |
|
@jonathanhefner / @dsp-ant - yes, moved it to a SEP at #1984 - closing this for now. |
7 participants
This PR introduces 6 new comprehensive tool annotations that provide rich metadata for tool management while maintaining backward compatibility and following MCP's principles of simplicity and concreteness. These annotations enable better governance policies, security controls, resource management, and user experience enhancements.
Motivation and Context
Organizations implementing MCP need better metadata about tools to support governance policies, security controls, and user experience enhancements. Currently, tool annotations are limited and don't provide sufficient information for:
This change addresses real implementation challenges from MCP adopters and provides concrete solutions for tool management at organizational scale.
How Has This Been Tested?
npm run validate:schemanpm run generate:jsonThe annotations have been tested across different organizational use cases including AI governance, security controls, and resource management scenarios.
Breaking Changes
None. All new annotations are optional with sensible defaults and maintain existing patterns and conventions. This PR only updates the draft specification - the stable 2025-03-26 version remains unchanged.
Types of changes
Checklist
Additional context
New Tool Annotations
aiProcessingHintslowExecutionHintresourceIntensiveHintsensitiveDataHintprivilegedAccessHintreversibleHintKey Design Decisions
Example Usage
AI-Powered Tool:
{ "name": "ai_code_analyzer", "annotations": { "title": "AI Code Analyzer", "readOnlyHint": true, "aiProcessingHint": true, "slowExecutionHint": true, "sensitiveDataHint": true, "openWorldHint": true } }System Administration Tool:
{ "name": "restart_service", "annotations": { "title": "Restart Service", "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "privilegedAccessHint": true, "reversibleHint": true } }Benefits and Impact
This enhancement provides the foundation for tool management UIs with rich categorization, governance dashboards for compliance tracking, and enhanced security controls.