Fix/tool annotations mapping

.wp-env.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
-	"core": null,
+	"core": "WordPress/WordPress#master",
 	"plugins": ["WordPress/abilities-api", "./."],
 	"env": {
 		"development": {

docs/guides/creating-abilities.md

@@ -58,32 +58,116 @@ wp_register_ability('my-plugin/my-ability', [
 
 ## MCP Annotations
 
-Annotations provide behavior hints to MCP clients about how to handle your abilities. **All component types** (Tools, Resources, and Prompts) support annotations through the `meta.annotations` field:
+Annotations provide behavior hints to MCP clients about how to handle your abilities. **Annotations are type-specific** - Tools use different annotations than Resources and Prompts.
+
+### Annotation Format: WordPress Abilities API vs MCP
+
+**Best Practice: Use WordPress Abilities API Format**
+
+The MCP Adapter automatically converts WordPress Abilities API annotation names to MCP format. **It's recommended to use the WordPress Abilities API format** when available for consistency across the WordPress ecosystem.
+
+#### For Tools: WordPress Format Preferred
+
+```php
+// ✅ RECOMMENDED: WordPress Abilities API format
+'meta' => [
+    'annotations' => [
+        'readonly' => true,        // Auto-converted to readOnlyHint
+        'destructive' => false,    // Auto-converted to destructiveHint
+        'idempotent' => true,      // Auto-converted to idempotentHint
+        'openWorldHint' => false,  // No WordPress equivalent, use MCP format
+        'title' => 'My Tool'       // No WordPress equivalent, use MCP format
+    ]
+]
+
+// ✅ ALSO VALID: Direct MCP format
+'meta' => [
+    'annotations' => [
+        'readOnlyHint' => true,
+        'destructiveHint' => false,
+        'idempotentHint' => true,
+        'openWorldHint' => false,
+        'title' => 'My Tool'
+    ]
+]
+```
+
+**Tool Annotation Mapping Table:**
+
+| WordPress Format | MCP Format | Description |
+|-----------------|------------|-------------|
+| `readonly` | `readOnlyHint` | Tool doesn't modify data |
+| `destructive` | `destructiveHint` | Tool may delete/destroy data |
+| `idempotent` | `idempotentHint` | Same input → same output |
+| *(no equivalent)* | `openWorldHint` | Can work with arbitrary data |
+| *(no equivalent)* | `title` | Custom display title |
+
+**Why Use WordPress Format?**
+- **Consistency**: Matches WordPress Abilities API conventions
+- **Familiarity**: WordPress developers already know these terms
+- **Future-proof**: Additional WordPress formats may be added
+- **Interoperability**: Works with other WordPress Abilities API consumers
+
+#### For Resources & Prompts: MCP Format Only
+
+Resources and Prompts use MCP format directly - there are no WordPress equivalents:
+
+```php
+'meta' => [
+    'annotations' => [
+        'audience' => ['user', 'assistant'],      // MCP format (no WordPress equivalent)
+        'lastModified' => '2024-01-15T10:30:00Z', // MCP format (no WordPress equivalent)
+        'priority' => 0.8                         // MCP format (no WordPress equivalent)
+    ]
+]
+```
+
+### Tool Annotations (ToolAnnotations)
+
+Tools support these MCP specification annotations:
 
 ```php
 'meta' => [
     'annotations' => [
-        'priority' => 1.0,              // Execution priority (higher = more important)
-        'readOnlyHint' => true,          // Component doesn't modify data
-        'destructiveHint' => false,      // Component doesn't delete/destroy data
-        'idempotentHint' => true,        // Same input always produces same output
-        'openWorldHint' => false,        // Component works with predefined data only
+        'readOnlyHint' => true,       // Tool doesn't modify data
+        'destructiveHint' => false,   // Tool doesn't delete/destroy data
+        'idempotentHint' => true,     // Same input → same output
+        'openWorldHint' => false,     // Works with predefined data only
+        'title' => 'Custom Title'     // Display title (optional)
     ]
 ]
 ```
 
-### Standard MCP Annotations
+**Supported Tool Annotation Fields:**
+- `readOnlyHint` (bool): Tool doesn't modify data
+- `destructiveHint` (bool): Tool may delete or destroy data
+- `idempotentHint` (bool): Same input always produces same output
+- `openWorldHint` (bool): Tool can work with arbitrary/unknown data
+- `title` (string): Custom display title for the tool
+
+**WordPress → MCP Field Conversion**: For backward compatibility, Tools support WordPress-format field names that are automatically converted:
+- `readonly` → `readOnlyHint`
+- `destructive` → `destructiveHint`
+- `idempotent` → `idempotentHint`
+
+### Resource & Prompt Annotations (Annotations)
+
+Resources and Prompts share the same annotation schema per MCP specification:
 
-**Universal Annotations** (supported by all component types):
-- `priority` (float): Execution priority (default: 1.0, higher = more important)
-- `readOnlyHint` (bool): Indicates read-only operations
-- `destructiveHint` (bool): Warns about destructive operations  
-- `idempotentHint` (bool): Same input produces same output
-- `openWorldHint` (bool): Can work with arbitrary/unknown data
+```php
+'meta' => [
+    'annotations' => [
+        'audience' => ['user', 'assistant'],      // Intended audience
+        'lastModified' => '2024-01-15T10:30:00Z', // ISO 8601 timestamp
+        'priority' => 0.8                         // 0.0 (lowest) to 1.0 (highest)
+    ]
+]
+```
 
-**Resource-Specific Annotations** (as per MCP specification):
-- `audience` (array): Intended audience (`["user", "assistant"]`)
+**Supported Resource & Prompt Annotation Fields:**
+- `audience` (array): Intended roles - `["user"]`, `["assistant"]`, or both
 - `lastModified` (string): ISO 8601 timestamp of last modification
+- `priority` (float): Relative importance (0.0 = lowest, 1.0 = highest)
 
 ### Annotation Usage by Component Type
 
@@ -94,7 +178,7 @@ Annotations provide behavior hints to MCP clients about how to handle your abili
 ### Complete Annotation Example
 
 ```php
-// Tool with comprehensive annotations
+// Tool with WordPress Abilities API format (RECOMMENDED)
 wp_register_ability('my-plugin/analyze-data', [
     'label' => 'Data Analyzer',
     'description' => 'Analyze data with various algorithms',
@@ -103,16 +187,20 @@ wp_register_ability('my-plugin/analyze-data', [
     'permission_callback' => function() { return current_user_can('read'); },
     'meta' => [
         'annotations' => [
-            'priority' => 2.0,              // High priority
-            'readOnlyHint' => true,          // Read-only operation
-            'destructiveHint' => false,      // Safe operation
-            'idempotentHint' => true,        // Consistent results
-            'openWorldHint' => false         // Works with known data
+            'readonly' => true,              // WordPress format → readOnlyHint
+            'destructive' => false,          // WordPress format → destructiveHint
+            'idempotent' => true,            // WordPress format → idempotentHint
+            'openWorldHint' => false,        // No WordPress equivalent
+            'title' => 'Data Analysis Tool'  // No WordPress equivalent
+        ],
+        'mcp' => [
+            'public' => true,
+            'type' => 'tool'
         ]
     ]
 ]);
 
-// Resource with MCP-specific annotations
+// Resource with Resource-specific annotations
 wp_register_ability('my-plugin/user-data', [
     'label' => 'User Data Resource',
     'description' => 'Access to user profile data',
@@ -123,27 +211,37 @@ wp_register_ability('my-plugin/user-data', [
         'annotations' => [
             'audience' => ['assistant'],     // For AI use only
             'priority' => 0.9,              // High importance
-            'lastModified' => date('c'),     // ISO 8601 timestamp
-            'readOnlyHint' => true
+            'lastModified' => date('c')      // ISO 8601 timestamp
+        ],
+        'mcp' => [
+            'public' => true,
+            'type' => 'resource'
         ]
     ]
 ]);
 
-// Prompt with behavior annotations
+// Prompt with Prompt-specific annotations
 wp_register_ability('my-plugin/review-prompt', [
     'label' => 'Code Review Prompt',
     'description' => 'Generate structured code review prompts',
+    'input_schema' => [
+        'type' => 'object',
+        'properties' => [
+            'code' => ['type' => 'string', 'description' => 'Code to review']
+        ],
+        'required' => ['code']
+    ],
     'execute_callback' => 'generate_review_prompt',
     'permission_callback' => function() { return current_user_can('edit_posts'); },
     'meta' => [
-        'arguments' => [
-            ['name' => 'code', 'description' => 'Code to review', 'required' => true]
-        ],
         'annotations' => [
-            'priority' => 1.5,              // Above average priority
-            'readOnlyHint' => true,          // Doesn't modify data
-            'idempotentHint' => true,        // Consistent output
-            'openWorldHint' => true          // Can handle any code
+            'audience' => ['user', 'assistant'], // For both user and AI
+            'priority' => 0.8,                  // High priority
+            'lastModified' => date('c')          // Current timestamp
+        ],
+        'mcp' => [
+            'public' => true,
+            'type' => 'prompt'
         ]
     ]
 ]);
@@ -202,9 +300,9 @@ wp_register_ability('my-plugin/create-post', [
     },
     'meta' => [
         'annotations' => [
-            'priority' => 2.0,
-            'readOnlyHint' => false,
-            'destructiveHint' => false
+            'readonly' => false,       // Tool modifies data (WordPress format)
+            'destructive' => false,    // Tool doesn't delete data (WordPress format)
+            'idempotent' => false      // Multiple calls create multiple posts (WordPress format)
         ],
         'mcp' => [
             'public' => true  // Expose this ability via MCP
@@ -236,11 +334,9 @@ wp_register_ability('my-plugin/site-config', [
     'meta' => [
         'uri' => 'wordpress://site/config',
         'annotations' => [
-            'readOnlyHint' => true,
-            'idempotentHint' => true,
-            'audience' => ['user', 'assistant'],
-            'priority' => 0.8,
-            'lastModified' => '2024-01-15T10:30:00Z'
+            'audience' => ['user', 'assistant'], // For both users and AI
+            'priority' => 0.8,                  // High priority resource
+            'lastModified' => '2024-01-15T10:30:00Z' // Last update timestamp
         ],
         'mcp' => [
             'public' => true,      // Expose this ability via MCP
@@ -317,8 +413,8 @@ wp_register_ability('my-plugin/code-review', [
     },
     'meta' => [
         'annotations' => [
-            'readOnlyHint' => true,      // Template doesn't modify data
-            'idempotentHint' => true     // Consistent prompt generation
+            'audience' => ['user'],         // For user-facing prompts
+            'priority' => 0.7               // Standard priority
         ],
         'mcp' => [
             'public' => true,   // Expose this ability via MCP
@@ -382,8 +478,9 @@ wp_register_ability('my-plugin/analysis-prompt', [
     },
     'meta' => [
         'annotations' => [
-            'readOnlyHint' => true,
-            'openWorldHint' => true              // Can handle any data type
+            'audience' => ['assistant'],        // For AI analysis only
+            'priority' => 0.9,                 // High priority analysis
+            'lastModified' => date('c')         // Current timestamp
         ],
         'mcp' => [
             'public' => true,   // Expose this ability via MCP
@@ -398,7 +495,7 @@ wp_register_ability('my-plugin/analysis-prompt', [
 **Template-Level Annotations** (in `meta.annotations`):
 - Apply to the prompt template itself
 - Describe the prompt's behavior characteristics
-- Support all standard MCP annotations (readOnlyHint, idempotentHint, etc.)
+- Support Prompt-specific annotations: `audience`, `priority`, `lastModified`
 
 **Message Content Annotations** (in message `content.annotations`):
 - Apply to individual messages within the prompt