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 |
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.