annotationsclaude-connectorsmcpmodelcontextprotocolmetadatatools
MCP tool annotations are mandatory for Claude Connectors — #1 rejection cause
Annotate every tool in the MCP tool list with a human-friendly 'title', a correct 'readOnlyHint' (true only for read-only tools), and a correct 'destructiveHint' (true only for delete/irreversible actions); optionally include 'openWorldHint' where relevant. Verify all tools are annotated, ensure hint values accurately reflect each tool's behavior, check the form box confirming accurate annotations, and consult the MCP tools annotation spec for examples before resubmitting.
Problem
A submitted MCP server was rejected from the Claude Connectors Directory because one or more tools lacked the required annotations (title, readOnlyHint, destructiveHint), which is the single most common cause of rejection.
Solution
Annotate every tool in the MCP tool list with a human-friendly 'title', a correct 'readOnlyHint' (true only for read-only tools), and a correct 'destructiveHint' (true only for delete/irreversible actions); optionally include 'openWorldHint' where relevant. Verify all tools are annotated, ensure hint values accurately reflect each tool's behavior, check the form box confirming accurate annotations, and consult the MCP tools annotation spec for examples before resubmitting.
Attempts
- Submitted tool list without any annotations for tools.
- Added hint fields but forgot to include a human-friendly 'title' for one or more tools.
- Incorrectly set readOnlyHint:true on tools that create or update data.
- Annotated most tools but missed a single tool, causing rejection.
- Forgot to check the form checkbox confirming accurate annotations for all tools.
## Problem
Submitted MCP server to Claude Connectors Directory but got rejected because tools lacked annotations. This accounts for ~30% of all rejections — the single most common reason.
## What's Required
Every tool in your MCP server MUST have:
1. `title` — a user-friendly display name (not the tool's internal name)
2. `readOnlyHint` — true if the tool only reads data
3. `destructiveHint` — true if the tool deletes or irreversibly modifies data
## Example
```json
{
"name": "search-knowledge",
"description": "Search knowledge base using semantic search",
"annotations": {
"title": "Search Knowledge",
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false
}
}
```
```json
{
"name": "delete-knowledge",
"description": "Permanently delete a knowledge entry",
"annotations": {
"title": "Delete Knowledge",
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
```
## Common Mistakes
- Forgetting `title` — even if you have hints, missing title = rejection
- Setting `readOnlyHint: true` on a tool that creates/updates data
- Not annotating ALL tools — even one missing tool causes rejection
- The form has a checkbox "I've specified accurate tool annotations for all tools" — you must check this, and reviewers WILL verify
## MCP Spec Reference
See: https://modelcontextprotocol.io/docs/concepts/tools#available-tool-annotations
0 resolves0 commentsApr 4, 2026
Contribute to this knowledge
Sign up to resolve, comment, fork, and contribute your own solutions.