@respira/wordpress-mcp-server 8.3.10 → 8.3.12

package/dist/server.js

@@ -302,6 +302,32 @@ function hoistDroppedStylingWarnings(result) {
  *     flipping the global current site (different intent from per-call override)
  *   - redeem_token: pre-site setup; no site exists yet
  */
+/**
+ * Pull the builder a tool actually acted through out of its response.
+ *
+ * Responses are not uniform about this. Element operations return
+ * `builder: { name, version }`, extract/inject return a bare `builder` string,
+ * and builder-info style responses use `active_builder` or `page_builder`.
+ * Accepting all three is cheaper than making every tool agree, and a null here
+ * is exactly as informative as the column was before: empty.
+ *
+ * The ingest endpoint lowercases and strips this to [a-z0-9_-], so no
+ * normalisation is needed on the way out.
+ */
+function telemetryBuilderName(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const candidates = [result.builder, result.active_builder, result.page_builder];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim()) {
+            return candidate.trim().slice(0, 40);
+        }
+        if (candidate && typeof candidate === 'object' && typeof candidate.name === 'string' && candidate.name.trim()) {
+            return candidate.name.trim().slice(0, 40);
+        }
+    }
+    return null;
+}
 const SITE_AGNOSTIC_TOOLS = new Set([
     'wordpress_list_sites',
     'wordpress_get_active_site',
@@ -372,6 +398,76 @@ const TOOLS_WITH_PAGINATION_HINT = {
     wordpress_extract_builder_content: 'This tool has no pagination and always returns the whole page. Use wordpress_find_builder_targets instead, which takes query, limit and offset and reports total_matches / has_more / next_offset, or wordpress_find_element to jump straight to one element. wordpress_get_page_outline gives a row-level summary. If you genuinely need the entire structure in one call, raise the cap with RESPIRA_MAX_TOOL_RESULT_BYTES.',
     respira_list_plugins: 'No pagination arg today. The full plugin list is usually small; consider filing a feature request if your site hits the cap here.',
 };
+/**
+ * The read/search tools where "nothing matched" is a complete answer.
+ *
+ * An explicit list, not a regex on the tool name. `find_builder_targets` and
+ * `find_element` both start with "find" and so does nothing else that writes,
+ * but a name-shaped rule would quietly start swallowing errors the first time
+ * someone adds `find_and_replace`. The cost of this list is remembering to add
+ * to it; the cost of the regex is a silent write failure, and this codebase has
+ * paid that one before.
+ *
+ * Names are matched after stripping the `respira_` / `wordpress_` prefix, since
+ * both surfaces exist and the telemetry shows both in use.
+ */
+export const EMPTY_READ_TOOLS = new Set([
+    'find_element',
+    'find_builder_targets',
+    'get_option',
+    'get_media',
+    'get_post_type',
+    'get_custom_post',
+    'get_term',
+    'get_menu',
+    'get_menu_item',
+    'get_page_outline',
+    'read_page',
+    'read_page_v2',
+    'read_post',
+    'read_post_v2',
+    'read_custom_post_v2',
+    'read_theme_file',
+    'extract_builder_content',
+]);
+/**
+ * "Not found" codes that mean the search came back empty.
+ *
+ * respira_site_id_not_found is deliberately absent: that is the caller naming a
+ * site that does not exist, which is a caller mistake on any tool and must stay
+ * an error. It was 410 calls over 25 sites in the 30 days to 2026-08-24, and
+ * folding it in here would hide a misconfigured client behind a friendly
+ * "nothing matched".
+ */
+export const EMPTY_READ_CODES = new Set([
+    'respira_element_not_found',
+    'respira_option_not_found',
+    'respira_post_not_found',
+    'respira_page_not_found',
+    'respira_post_type_not_found',
+    'respira_media_not_found',
+    'respira_theme_file_not_found',
+    'respira_module_not_found',
+    'respira_acf_group_not_found',
+    'respira_acf_post_not_found',
+]);
+/** The WP_Error code, which wordpress-client promotes onto error.name. */
+export function readErrorCode(error) {
+    const fromName = typeof error?.name === 'string' ? error.name : '';
+    const fromCode = typeof error?.code === 'string' ? error.code : '';
+    return fromCode || fromName || '';
+}
+/**
+ * True when this is a read/search tool reporting that nothing matched.
+ * Both halves must hold: the wrong tool with the right code, or the right tool
+ * with any other code, stays an error.
+ */
+export function isEmptyReadResult(toolName, error) {
+    const bare = String(toolName || '').replace(/^(respira_|wordpress_)+/, '');
+    if (!EMPTY_READ_TOOLS.has(bare))
+        return false;
+    return EMPTY_READ_CODES.has(readErrorCode(error));
+}
 export class RespiraWordPressServer {
     server;
     currentSite = null;
@@ -1789,6 +1885,53 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     clearTimeout(timeoutHandle);
                 }
                 this.currentSite?.setCurrentToolName(null);
+                // A search that matched nothing is an answer, not a failure.
+                //
+                // Telemetry, 30 days to 2026-08-24: respira_element_not_found is the
+                // single largest caller_error code at 4,626 calls, and 4,278 of those
+                // (92.5%) come from find_element itself. The same shape repeats on
+                // get_option (632 calls / 173 sites), read_post, get_post_type,
+                // read_page, get_media and read_theme_file. Across the read surface
+                // that is 5,695 calls over 318 of 716 sites, reported to the agent as
+                // errors when the honest answer is "nothing matched".
+                //
+                // It costs more than a wrong statistic. An agent that gets an error
+                // back from find_element cannot tell "this page has no such element,
+                // try another identifier" from "the tool or the site is broken". The
+                // first should prompt a different query and the second should prompt a
+                // stop, and today they are indistinguishable, so agents give up on
+                // pages they could have edited.
+                //
+                // Deliberately narrow, because turning an error into a success is the
+                // exact direction this codebase's worst bugs went:
+                //   - only read/search tools, never a write. On a write, "not found"
+                //     means the caller targeted something that does not exist and it
+                //     must stay an error.
+                //   - only *_not_found codes, and never respira_site_id_not_found: a
+                //     bad site id IS a caller mistake and stays loud.
+                //   - the payload says found: false and matches: [] in as many words.
+                //     It never fabricates a result, and isError stays false only
+                //     because the question was answered.
+                if (isEmptyReadResult(name, error)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    found: false,
+                                    matches: [],
+                                    tool: name,
+                                    reason: readErrorCode(error),
+                                    message: 'Nothing matched. This is a complete answer, not a failure: the site responded and ' +
+                                        'contains no item matching what was asked for. Try a different identifier rather than ' +
+                                        'retrying the same one. For elements, identifier_type "content" searches visible text ' +
+                                        'and "path" names exactly one element; respira_get_page_outline lists what is actually ' +
+                                        'on the page.',
+                                }),
+                            },
+                        ],
+                    };
+                }
                 if (error instanceof ToolTimeoutError) {
                     const activeSite = this.getActiveSiteSummary(args);
                     return {
@@ -2010,7 +2153,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Site Context",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_sites',
@@ -2019,7 +2168,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Sites",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_divi_migration_readiness',
@@ -2033,7 +2188,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Divi Migration Readiness",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_search_abilities',
@@ -2049,7 +2210,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         limit: { type: 'number', description: 'Maximum results, 1–100 (default 20).' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Search Abilities",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_abilities_gap_report',
@@ -2061,7 +2228,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Abilities Gap Report",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_invoke_ability',
@@ -2084,6 +2257,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['ability'],
                 },
+                annotations: {
+                    title: "Invoke Ability",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_active_site',
@@ -2092,7 +2272,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Active Site",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_theme_docs',
@@ -2101,7 +2287,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Theme Documentation",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_builder_info',
@@ -2115,7 +2307,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Builder Info",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_pages',
@@ -2145,7 +2343,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Pages",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_read_page',
@@ -2164,7 +2368,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Read Page",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_page_duplicate',
@@ -2183,6 +2393,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['original_id'],
                 },
+                annotations: {
+                    title: "Duplicate Page",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_page',
@@ -2242,7 +2459,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Page",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_page',
@@ -2269,7 +2492,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Page",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_posts',
@@ -2299,7 +2528,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Posts",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_read_post',
@@ -2318,7 +2553,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Read Post",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_post_duplicate',
@@ -2337,6 +2578,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['original_id'],
                 },
+                annotations: {
+                    title: "Duplicate Post",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'respira_duplicate_with_translations',
@@ -2364,6 +2612,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id'],
                 },
+                annotations: {
+                    title: "Duplicate With Translations",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_translations',
@@ -2376,6 +2631,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
+                annotations: {
+                    title: "Get Translations",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_translation',
@@ -2390,6 +2652,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['source_id', 'target_language'],
                 },
+                annotations: {
+                    title: "Create Translation",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_translation',
@@ -2405,6 +2674,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['source_id', 'target_language'],
                 },
+                annotations: {
+                    title: "Update Translation",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_theme_builder_templates',
@@ -2413,6 +2689,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
+                annotations: {
+                    title: "List Theme Templates",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_theme_builder_template',
@@ -2434,6 +2717,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['kind', 'name'],
                 },
+                annotations: {
+                    title: "Create Theme Template",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_theme_builder_template',
@@ -2450,6 +2740,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['layout_id', 'structure'],
                 },
+                annotations: {
+                    title: "Update Theme Template",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_build_mega_menu',
@@ -2489,6 +2786,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['menu_name', 'top_label', 'columns'],
                 },
+                annotations: {
+                    title: "Build Mega Menu",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_post',
@@ -2587,7 +2891,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Post",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_post',
@@ -2614,7 +2924,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Post",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_media',
@@ -2636,7 +2952,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Media",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_upload_media',
@@ -2671,6 +2993,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['file', 'filename'],
                 },
+                annotations: {
+                    title: "Upload Media",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_extract_builder_content',
@@ -2689,7 +3018,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Extract Builder Content",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_find_builder_targets',
@@ -2720,7 +3055,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['builder', 'page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Find Builder Targets",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_page_outline',
@@ -2739,7 +3080,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Page Outline",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_builder_inline_schemas',
@@ -2759,7 +3106,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: [],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Builder Inline Schemas",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_inject_builder_content',
@@ -2801,7 +3154,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['builder', 'page_id', 'content'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Inject Builder Content",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_make_responsive',
@@ -2820,6 +3179,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
+                annotations: {
+                    title: "Make Page Responsive",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_module',
@@ -2883,7 +3249,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['builder', 'page_id', 'module_identifier', 'updates'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Module",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_snapshots',
@@ -2913,7 +3285,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Snapshots",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_snapshot',
@@ -2934,7 +3312,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['snapshot_uuid'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Snapshot",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_diff_snapshots',
@@ -2953,7 +3337,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['snapshot_uuid_a', 'snapshot_uuid_b'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Diff Snapshots",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_restore_snapshot',
@@ -2968,7 +3358,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['snapshot_uuid'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Restore Snapshot",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_restore_session',
@@ -2980,17 +3376,37 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['session_id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Restore Session",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_begin_session',
                 description: 'Begin an explicit snapshot session. Every change made after this (until wordpress_end_session) is grouped under one session_id, so the whole batch can be rolled back together with wordpress_restore_session. Returns the session_id. Without an explicit session, changes are auto-grouped by a time window.',
                 inputSchema: { type: 'object', properties: {} },
+                annotations: {
+                    title: "Begin Snapshot Session",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_end_session',
                 description: 'End the explicit snapshot session started by wordpress_begin_session. Later changes fall back to automatic time-window grouping.',
                 inputSchema: { type: 'object', properties: {} },
+                annotations: {
+                    title: "End Snapshot Session",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_site_templates',
@@ -3006,7 +3422,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         per_page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Site Templates",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_activity',
@@ -3024,7 +3446,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         per_page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Activity",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_activity',
@@ -3034,7 +3462,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'number' } },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Activity Record",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_site_template',
@@ -3047,7 +3481,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Site Template",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_site_template',
@@ -3067,6 +3507,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
+                annotations: {
+                    title: "Create Site Template",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_site_template',
@@ -3084,6 +3531,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'expected_fingerprint', 'operations'],
                 },
+                annotations: {
+                    title: "Update Site Template",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_reset_site_template',
@@ -3099,7 +3553,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'expected_fingerprint'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Reset Site Template",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_site_patterns',
@@ -3114,7 +3574,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         per_page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Site Patterns",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_site_pattern',
@@ -3124,7 +3590,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'string', description: 'User pattern post ID, registered pattern name, or slug.' } },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Site Pattern",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_site_pattern',
@@ -3147,6 +3619,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['title'],
                 },
+                annotations: {
+                    title: "Create Site Pattern",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_site_pattern',
@@ -3167,6 +3646,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'expected_fingerprint', 'operations'],
                 },
+                annotations: {
+                    title: "Update Site Pattern",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_site_pattern',
@@ -3186,7 +3672,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'expected_fingerprint'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Site Pattern",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_site_navigations',
@@ -3199,7 +3691,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         per_page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Site Navigations",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_site_navigation',
@@ -3209,7 +3707,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'string', description: 'Navigation post ID or slug.' } },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Site Navigation",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_site_navigation',
@@ -3231,6 +3735,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['title'],
                 },
+                annotations: {
+                    title: "Create Site Navigation",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_site_navigation',
@@ -3251,6 +3762,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'expected_fingerprint', 'operations'],
                 },
+                annotations: {
+                    title: "Update Site Navigation",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_site_navigation',
@@ -3270,7 +3788,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'expected_fingerprint'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Site Navigation",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_design_tokens',
@@ -3280,7 +3804,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { type: { type: 'string', enum: ['color', 'typography', 'spacing', 'breakpoints'] } },
                     required: ['type'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Design Tokens",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_design_token',
@@ -3307,6 +3837,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'name', 'value'],
                 },
+                annotations: {
+                    title: "Create Design Token",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_design_token',
@@ -3333,7 +3870,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'id', 'expected_fingerprint'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Design Token",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_design_token',
@@ -3350,7 +3893,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'id', 'expected_fingerprint'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Design Token",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_design_direction',
@@ -3361,7 +3910,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         id: { type: 'number', description: 'Optional direction id. Omit to read the ACTIVE direction.' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Design Direction",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_design_directions',
@@ -3370,7 +3925,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Design Directions",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_save_design_direction',
@@ -3386,6 +3947,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['document'],
                 },
+                annotations: {
+                    title: "Save Design Direction",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_activate_design_direction',
@@ -3403,7 +3971,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Activate Design Direction",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_deactivate_design_direction',
@@ -3424,7 +3998,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: [],
                 },
-                idempotentHint: false,
+                annotations: {
+                    title: "Deactivate Design Direction",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_design_direction',
@@ -3442,7 +4022,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Design Direction",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_import_design_tokens',
@@ -3466,6 +4052,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['tokens'],
                 },
+                annotations: {
+                    title: "Import Design Tokens",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_apply_design_direction',
@@ -3483,7 +4076,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         edit_target: { type: 'string', enum: ['approval', 'live'] },
                     },
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Apply Design Direction",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_export_design_direction',
@@ -3494,7 +4093,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         id: { type: 'number', description: 'Optional direction id; omit for the active direction.' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Export Design Direction",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_check_design',
@@ -3529,8 +4134,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
-                idempotentHint: true,
+                annotations: {
+                    title: "Check Design",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'wordpress_mint_design_preview',
@@ -3544,7 +4154,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Mint Design Preview",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_design_apply_reports',
@@ -3558,8 +4174,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
-                idempotentHint: true,
+                annotations: {
+                    title: "Design Apply Reports",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_apply_builder_patch',
@@ -3619,7 +4240,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['builder', 'post_id', 'operations'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Apply Builder Patch",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_validate_security',
@@ -3634,6 +4261,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['content'],
                 },
+                annotations: {
+                    title: "Validate Content Security",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_read_theme_file',
@@ -3648,7 +4282,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['relative_path'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Read Theme File",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_write_theme_file',
@@ -3667,6 +4307,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['relative_path', 'content'],
                 },
+                annotations: {
+                    title: "Write Theme File",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_append_theme_file',
@@ -3685,6 +4332,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['relative_path', 'content'],
                 },
+                annotations: {
+                    title: "Append Theme File",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_switch_site',
@@ -3699,6 +4353,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['site_id'],
                 },
+                annotations: {
+                    title: "Switch Site",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_diagnose_connection',
@@ -3718,7 +4379,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Diagnose Connection",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 // v6.17: docs search. Hits respira.press/docs-search which is a
@@ -3737,7 +4404,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         limit: { type: 'number', description: 'Max results to return. 1-10. Default 5.', minimum: 1, maximum: 10 },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Search Documentation",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 // v6.17: agent-side bug reporting. The AI client (Claude, Cursor,
@@ -3777,7 +4450,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: false,
+                annotations: {
+                    title: "Report Issue",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
             },
             {
                 // Canonical name is wordpress_* so generateDualTools creates the
@@ -3799,6 +4478,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['token'],
                 },
+                annotations: {
+                    title: "Redeem Install Token",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             // Page Speed Analysis tools
             {
@@ -3814,7 +4500,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Performance Analysis",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_core_web_vitals',
@@ -3829,7 +4521,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Core Web Vitals",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 // Phase E Tier 2 (v6.19.0): real PageSpeed Insights v5 audit. The
@@ -3852,7 +4550,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         { required: ['url'] },
                     ],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "PageSpeed Audit",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 // Phase E Tier 2 (v6.19.0): standard-analyzer-envelope wrapper around
@@ -3875,7 +4579,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         { required: ['url'] },
                     ],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze PageSpeed",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'wordpress_analyze_images',
@@ -3890,7 +4600,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze Images",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // SEO Analysis tools
             {
@@ -3906,7 +4622,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze SEO",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_check_seo_issues',
@@ -3921,7 +4643,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Check SEO Issues",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_analyze_readability',
@@ -3936,7 +4664,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze Readability",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_analyze_rankmath',
@@ -3951,7 +4685,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze Rank Math",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // AEO (AI Engine Optimization) tools
             {
@@ -3967,7 +4707,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze AEO",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_check_structured_data',
@@ -3982,7 +4728,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Check Structured Data",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Safety & Security center
             {
@@ -4003,7 +4755,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Security Audit",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'wordpress_update_core_security',
@@ -4030,7 +4788,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['advisory_id', 'target_version', 'backup_confirmed'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Core Security",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             // Accessibility tools
             {
@@ -4044,7 +4808,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         summary_only: { type: 'boolean', description: 'When true (default), strips violations[].nodes and prompts[] from each entry. The full payload remains available via respira_get_accessibility_scan.' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Accessibility Scans",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_accessibility_scan',
@@ -4057,7 +4827,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['scan_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Accessibility Scan",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_scan_page_accessibility',
@@ -4071,6 +4847,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_id'],
                 },
+                annotations: {
+                    title: "Run Accessibility Scan",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_apply_accessibility_fixes',
@@ -4087,6 +4870,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['scan_id'],
                 },
+                annotations: {
+                    title: "Apply Accessibility Fixes",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Plugin Management tools (EXPERIMENTAL)
             {
@@ -4096,7 +4886,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Plugins",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_install_plugin',
@@ -4120,6 +4916,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug_or_url'],
                 },
+                annotations: {
+                    title: "Install Plugin",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'wordpress_activate_plugin',
@@ -4142,6 +4945,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
+                annotations: {
+                    title: "Activate Plugin",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_deactivate_plugin',
@@ -4160,6 +4970,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
+                annotations: {
+                    title: "Deactivate Plugin",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_plugin',
@@ -4178,7 +4995,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Plugin",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'wordpress_delete_plugin',
@@ -4197,7 +5020,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Plugin",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Users Management
             {
@@ -4220,7 +5049,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Users",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_user',
@@ -4235,7 +5070,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get User",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_user',
@@ -4266,6 +5107,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['username', 'email', 'password'],
                 },
+                annotations: {
+                    title: "Create User",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_user',
@@ -4300,7 +5148,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update User",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_user',
@@ -4323,7 +5177,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete User",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Comments
             {
@@ -4350,7 +5210,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Comments",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_comment',
@@ -4365,7 +5231,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Comment",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_comment',
@@ -4400,6 +5272,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'author', 'author_email', 'content'],
                 },
+                annotations: {
+                    title: "Create Comment",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_comment',
@@ -4422,7 +5301,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Comment",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_comment',
@@ -4441,7 +5326,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Comment",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Taxonomies
             {
@@ -4451,7 +5342,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Taxonomies",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_taxonomy',
@@ -4466,7 +5363,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['taxonomy'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Taxonomy",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_terms',
@@ -4493,7 +5396,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['taxonomy'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Terms",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_term',
@@ -4512,7 +5421,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['taxonomy', 'id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Term",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_term',
@@ -4543,6 +5458,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['taxonomy', 'name'],
                 },
+                annotations: {
+                    title: "Create Term",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_term',
@@ -4577,7 +5499,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['taxonomy', 'id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Term",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_term',
@@ -4600,7 +5528,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['taxonomy', 'id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Term",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Custom Post Types
             {
@@ -4610,7 +5544,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Post Types",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_post_type',
@@ -4625,7 +5565,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Post Type",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Custom Structures (v7.1) — agent-creatable CPTs, taxonomies, ACF field groups.
             // Stored in wp_options on the WP side, registered against core via register_post_type
@@ -4652,6 +5598,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug', 'label'],
                 },
+                annotations: {
+                    title: "Create Post Type",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_post_type',
@@ -4672,6 +5625,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
+                annotations: {
+                    title: "Update Post Type",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_post_type',
@@ -4683,13 +5643,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Post Type",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_custom_post_types',
                 description: "List every Custom Post Type Respira created via wordpress_create_post_type. Different from wordpress_list_post_types — that one enumerates EVERY registered post type (core, theme, third-party, Respira-created). This one shows only Respira-owned ones, with their full definition + creation timestamp.",
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Custom Post Types",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_taxonomy',
@@ -4708,6 +5680,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug', 'label'],
                 },
+                annotations: {
+                    title: "Create Taxonomy",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_taxonomy',
@@ -4726,6 +5705,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
+                annotations: {
+                    title: "Update Taxonomy",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_taxonomy',
@@ -4737,13 +5723,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['slug'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Taxonomy",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_custom_taxonomies',
                 description: 'List every taxonomy Respira created. Different from wordpress_list_taxonomies — that one enumerates every registered taxonomy site-wide.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Custom Taxonomies",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_acf_field_group',
@@ -4758,6 +5756,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['title'],
                 },
+                annotations: {
+                    title: "Create ACF Field Group",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_acf_field_group',
@@ -4772,6 +5777,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['key'],
                 },
+                annotations: {
+                    title: "Update ACF Field Group",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_acf_field_group',
@@ -4783,13 +5795,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['key'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete ACF Field Group",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_acf_field_groups',
                 description: 'List every ACF field group Respira created. Requires ACF active. Refuses with respira_acf_not_active otherwise.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List ACF Field Groups",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Playbooks (v7.1) — JSON workflow compositions that register themselves as Abilities.
             // Once created, a playbook becomes callable via respira_invoke_ability under the
@@ -4823,12 +5847,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'label', 'input_schema', 'steps'],
                 },
+                annotations: {
+                    title: "Create Playbook",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_playbooks',
                 description: 'List every Playbook stored on this site, with id / ability_id / label / description / step count / invocation_count / last_invoked_at. Useful for "what playbooks are available" discovery before authoring a new one.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Playbooks",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_playbook',
@@ -4840,7 +5877,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Playbook",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_playbook',
@@ -4857,6 +5900,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
+                annotations: {
+                    title: "Update Playbook",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_playbook',
@@ -4868,7 +5918,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Playbook",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Site Memory (v8.3, Resonance) — persistent per-site memory that lives IN the
             // WordPress site, so it travels across clients (Claude, ChatGPT, Cursor) and
@@ -4891,6 +5947,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['key', 'content'],
                 },
+                annotations: {
+                    title: "Save Site Memory",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_forget',
@@ -4902,12 +5965,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['key'],
                 },
+                annotations: {
+                    title: "Forget Site Memory",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_memory',
                 description: 'List everything stored in this site\'s persistent Site Memory: facts, preferences, lessons, and enforced rules, with source and last-updated metadata. The same content arrives automatically in get_site_context; use this when you need keys for updating or forgetting entries.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Site Memory",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_list_custom_posts',
@@ -4942,7 +6018,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Custom Posts",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_custom_post',
@@ -4965,7 +6047,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Custom Post",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_custom_post',
@@ -5051,6 +6139,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'title'],
                 },
+                annotations: {
+                    title: "Create Custom Post",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_custom_post',
@@ -5149,7 +6244,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Custom Post",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_custom_post',
@@ -5180,7 +6281,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['type', 'id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Custom Post",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Options
             {
@@ -5195,7 +6302,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Options",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_option',
@@ -5210,7 +6323,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['option'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Option",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_option',
@@ -5228,7 +6347,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['option', 'value'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Option",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_option',
@@ -5247,7 +6372,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['option'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Option",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_purge_cache',
@@ -5267,7 +6398,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: [],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Purge Cache",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             // Media enhancements
             {
@@ -5283,7 +6420,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Media",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_media',
@@ -5310,7 +6453,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Media",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_media_batch',
@@ -5335,6 +6484,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['items'],
                 },
+                annotations: {
+                    title: "Batch Update Media",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_media',
@@ -5357,7 +6513,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Media",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Menu Management
             {
@@ -5367,7 +6529,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Menus",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_menu',
@@ -5382,7 +6550,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Menu",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_menu',
@@ -5401,6 +6575,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['name'],
                 },
+                annotations: {
+                    title: "Create Menu",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_menu',
@@ -5423,7 +6604,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Menu",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_menu',
@@ -5442,7 +6629,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Menu",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Menu Locations
             {
@@ -5452,7 +6645,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Menu Locations",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_assign_menu_location',
@@ -5471,7 +6670,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['location', 'menu_id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Assign Menu Location",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // Menu Items
             {
@@ -5487,7 +6692,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['menu_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Menu Items",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_create_menu_item',
@@ -5542,6 +6753,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['menu_id', 'title'],
                 },
+                annotations: {
+                    title: "Create Menu Item",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_get_menu_item',
@@ -5556,7 +6774,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['item_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Menu Item",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_menu_item',
@@ -5603,7 +6827,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['item_id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Menu Item",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_delete_menu_item',
@@ -5618,7 +6848,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['item_id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Menu Item",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
         ];
         // --- v5.2.0 Elemental: new tools ---
@@ -5791,7 +7027,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number', description: 'Page number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Products",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_product',
@@ -5803,7 +7045,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Product",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_product',
@@ -5828,6 +7076,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['name'],
                 },
+                annotations: {
+                    title: "Create Product",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_product',
@@ -5873,7 +7128,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Product",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_duplicate_product',
@@ -5885,6 +7146,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
+                annotations: {
+                    title: "Duplicate Product",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_categories',
@@ -5899,7 +7167,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number', description: 'Page number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Categories",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_category',
@@ -5911,7 +7185,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Category",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_category',
@@ -5926,6 +7206,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['name'],
                 },
+                annotations: {
+                    title: "Create Category",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_category',
@@ -5941,7 +7228,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Category",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_delete_category',
@@ -5953,7 +7246,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Category",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_tags',
@@ -5967,7 +7266,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number', description: 'Page number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Tags",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_tag',
@@ -5979,7 +7284,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Tag",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_tag',
@@ -5993,6 +7304,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['name'],
                 },
+                annotations: {
+                    title: "Create Tag",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_tag',
@@ -6007,7 +7325,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Tag",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_delete_tag',
@@ -6019,7 +7343,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Tag",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_orders',
@@ -6032,7 +7362,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number', description: 'Page number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Orders",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_order',
@@ -6044,7 +7380,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Order",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_order_status',
@@ -6057,7 +7399,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'status'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Order Status",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_stock_status',
@@ -6066,7 +7414,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Stock Status",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_stock',
@@ -6080,7 +7434,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Stock",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_sales_report',
@@ -6093,7 +7453,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         date_max: { type: 'string', description: 'End date for custom period' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Sales Report",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_revenue_summary',
@@ -6107,7 +7473,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         max_orders: { type: 'number', description: 'Bounded coverage cap, 1-10000. Defaults to 2000.' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Revenue Summary",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_sales_timeseries',
@@ -6122,7 +7494,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         max_orders: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Sales Timeseries",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_top_products',
@@ -6137,7 +7515,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         limit: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Top Products",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_orders_summary',
@@ -6151,7 +7535,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         max_orders: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Orders Summary",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_customers_summary',
@@ -6165,25 +7555,49 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         max_orders: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Customers Summary",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_store_configuration',
                 description: 'Read sanitized WooCommerce currency, timezone, tax, units, checkout, page, and HPOS configuration. Credentials and secrets are never returned.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Store Configuration",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_payment_gateways',
                 description: 'List payment gateway IDs, public titles, enabled state, and supported features without settings, credentials, or tokens.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Payment Gateways",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_shipping_zones',
                 description: 'List WooCommerce shipping zones, locations, and public method state.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Shipping Zones",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_tax_rates',
@@ -6192,7 +7606,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: { tax_class: { type: 'string', description: 'Empty for standard rates.' } },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Tax Rates",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_webhooks',
@@ -6201,7 +7621,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: { page: { type: 'number' }, per_page: { type: 'number' } },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Webhooks",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_webhook',
@@ -6211,7 +7637,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'number' } },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Webhook",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_webhook',
@@ -6227,6 +7659,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['topic', 'delivery_url'],
                 },
+                annotations: {
+                    title: "Create Webhook",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'woocommerce_update_webhook',
@@ -6244,7 +7683,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Webhook",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'woocommerce_delete_webhook',
@@ -6254,7 +7699,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'number' }, approval_token: { type: 'string' } },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Webhook",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_test_webhook',
@@ -6264,6 +7715,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'number' }, approval_token: { type: 'string' } },
                     required: ['id'],
                 },
+                annotations: {
+                    title: "Test Webhook",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
             },
             // --- Brands (addon v3.0) ---
             {
@@ -6278,7 +7736,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         hide_empty: { type: 'boolean', description: 'Only brands with products' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Brands",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_brand',
@@ -6290,7 +7754,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Brand",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_brand',
@@ -6304,6 +7774,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['name'],
                 },
+                annotations: {
+                    title: "Create Brand",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_brand',
@@ -6318,7 +7795,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Brand",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_delete_brand',
@@ -6330,7 +7813,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Delete Brand",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Catalog operations (addon v3.0 exposes existing REST tools) ---
             {
@@ -6353,7 +7842,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Advanced Product List",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_find_product',
@@ -6366,7 +7861,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['query'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Find Product",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_catalog_health',
@@ -6375,7 +7876,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Catalog Health",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_bulk_update_products',
@@ -6392,6 +7899,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['updates'],
                 },
+                annotations: {
+                    title: "Bulk Update Products",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Pricing (addon v3.0 exposes existing REST tools) ---
             {
@@ -6409,6 +7923,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['change_value'],
                 },
+                annotations: {
+                    title: "Bulk Update Prices",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_schedule_sale',
@@ -6424,6 +7945,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['product_ids'],
                 },
+                annotations: {
+                    title: "Schedule Sale",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_revert_pricing',
@@ -6436,7 +7964,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['product_id', 'snapshot_id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Revert Pricing",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Inventory (addon v3.0 exposes existing REST tools) ---
             {
@@ -6454,6 +7988,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['updates'],
                 },
+                annotations: {
+                    title: "Bulk Update Stock",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_find_low_stock',
@@ -6464,7 +8005,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         threshold: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Find Low Stock",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Storefront intelligence (addon v3.0 exposes existing REST tools) ---
             {
@@ -6476,7 +8023,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page_id: { type: 'number', description: 'Defaults to the WooCommerce shop page' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze Shop Page",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_analyze_product_page',
@@ -6488,7 +8041,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['product_id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze Product Page",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_product_card_layout',
@@ -6511,6 +8070,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['changes'],
                 },
+                annotations: {
+                    title: "Update Product Card Layout",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_add_low_stock_badge',
@@ -6534,6 +8100,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
+                annotations: {
+                    title: "Add Low Stock Badge",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_add_sale_badge',
@@ -6554,6 +8127,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                     },
                 },
+                annotations: {
+                    title: "Add Sale Badge",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_analyze_storefront_card',
@@ -6562,7 +8142,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Analyze Storefront Card",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_storefront_card_field',
@@ -6585,6 +8171,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['field', 'attributes'],
                 },
+                annotations: {
+                    title: "Update Storefront Card Field",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_checkout_layout',
@@ -6598,6 +8191,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['changes'],
                 },
+                annotations: {
+                    title: "Update Checkout Layout",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Variations and attributes (addon v3.0) ---
             {
@@ -6616,7 +8216,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'attributes'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Set Product Attributes",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_generate_variations',
@@ -6631,6 +8237,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
+                annotations: {
+                    title: "Generate Variations",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_variation',
@@ -6650,6 +8263,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'attributes'],
                 },
+                annotations: {
+                    title: "Create Variation",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_global_attribute',
@@ -6668,6 +8288,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['name'],
                 },
+                annotations: {
+                    title: "Create Global Attribute",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_variation_gallery',
@@ -6680,7 +8307,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'image_ids'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Set Variation Gallery",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Coupons and customers (addon v3.0) ---
             {
@@ -6694,7 +8327,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Coupons",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_coupon',
@@ -6720,6 +8359,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['code'],
                 },
+                annotations: {
+                    title: "Create Coupon",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_coupon',
@@ -6737,7 +8383,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Coupon",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_customer',
@@ -6754,6 +8406,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['email'],
                 },
+                annotations: {
+                    title: "Create Customer",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_customer',
@@ -6770,7 +8429,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Update Customer",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Order notes and refunds (addon v3.0) ---
             {
@@ -6785,6 +8450,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'note'],
                 },
+                annotations: {
+                    title: "Add Order Note",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_order_refunds',
@@ -6796,7 +8468,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Order Refunds",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_create_order_refund',
@@ -6814,7 +8492,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Create Order Refund",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
             },
             // --- Subscriptions / Bookings / Memberships (addon v3.1, extensions) ---
             {
@@ -6830,7 +8514,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Subscriptions",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_subscription',
@@ -6842,7 +8532,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Subscription",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_subscription_status',
@@ -6857,7 +8553,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'status'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Update Subscription Status",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_subscription_dates',
@@ -6873,7 +8575,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Update Subscription Dates",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_add_subscription_note',
@@ -6887,6 +8595,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'note'],
                 },
+                annotations: {
+                    title: "Add Subscription Note",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_bookings',
@@ -6900,7 +8615,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Bookings",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_booking',
@@ -6912,7 +8633,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Booking",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_booking_status',
@@ -6926,7 +8653,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'status'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Update Booking Status",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_reschedule_booking',
@@ -6942,7 +8675,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'start', 'end'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Reschedule Booking",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_membership_plans',
@@ -6951,7 +8690,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Membership Plans",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_memberships',
@@ -6966,7 +8711,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         page: { type: 'number' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Memberships",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_membership',
@@ -6978,7 +8729,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Membership",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_update_membership_status',
@@ -6993,7 +8750,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'membership_action'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Update Membership Status",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_membership_end_date',
@@ -7007,7 +8770,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'end_date'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Set Membership End Date",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Assisted checkout (addon v3.1) ---
             {
@@ -7027,6 +8796,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['items'],
                 },
+                annotations: {
+                    title: "Create Cart Link",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_agent_orders_report',
@@ -7037,14 +8813,26 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         days: { type: 'number', description: 'Period in days (default 30, max 365)' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Agent Orders Report",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Product configurator, STAGGS (addon v3.2) ---
             {
                 name: 'woocommerce_configurator_status',
                 description: 'Which product configurator is active (STAGGS) plus how many products and attribute groups use it. Start here before any configurator work.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Configurator Status",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_product_configurator',
@@ -7054,7 +8842,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'number', description: 'Product ID' } },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Product Configurator",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_product_configurator',
@@ -7068,12 +8862,25 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'enabled'],
                 },
+                annotations: {
+                    title: "Set Product Configurator",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_list_configurator_attributes',
                 description: 'List STAGGS attribute groups (the reusable option sets a configurator is built from): id, title, type.',
                 inputSchema: { type: 'object', properties: {} },
-                readOnlyHint: true,
+                annotations: {
+                    title: "List Configurator Attributes",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_configurator_attribute_items',
@@ -7083,7 +8890,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: { id: { type: 'number', description: 'STAGGS attribute (sgg_attribute) post ID' } },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Configurator Attribute Items",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_configurator_attribute_items',
@@ -7097,6 +8910,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'items'],
                 },
+                annotations: {
+                    title: "Set Configurator Attribute Items",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_plugin_state',
@@ -7110,7 +8930,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['plugin'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Get Plugin State",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_plugin_state',
@@ -7126,6 +8952,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['plugin'],
                 },
+                annotations: {
+                    title: "Set Plugin State",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Readiness autofix (addon v3.1) ---
             {
@@ -7138,7 +8971,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         target_score: { type: 'number', description: 'Skip products at or above this score (default 90)' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Readiness Fix List",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_image_alt',
@@ -7152,7 +8991,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id', 'alt'],
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Set Image Alt Text",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Product feeds + llms.txt (addon v3.1) ---
             {
@@ -7174,7 +9019,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         rotate_token: { type: 'boolean', description: 'Rotate the secret feed URLs' },
                     },
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Configure Product Feed",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_generate_feed',
@@ -7185,6 +9036,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         format: { type: 'string', description: 'Optional: enable and build one specific format' },
                     },
                 },
+                annotations: {
+                    title: "Generate Product Feed",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_get_feed_status',
@@ -7193,7 +9051,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Feed Status",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_repair_feed_scheduler',
@@ -7204,7 +9068,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         dry_run: { type: 'boolean', description: 'Inspect whether a stale lock would be repaired without changing scheduler state.' },
                     },
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Repair Feed Scheduler",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_validate_feed',
@@ -7216,7 +9086,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         limit: { type: 'number', description: 'Parent products to sample (default 100, max 200)' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Validate Feed",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_set_feed_category_mapping',
@@ -7227,7 +9103,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         mappings: { type: 'object', description: '{"<term_id>": "<google category id or full path>"}; empty string removes a mapping' },
                     },
                 },
-                idempotentHint: true,
+                annotations: {
+                    title: "Set Feed Category Mapping",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- AI readiness (addon v3.0) ---
             {
@@ -7240,7 +9122,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['id'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Product AI Readiness",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'woocommerce_catalog_ai_readiness',
@@ -7251,7 +9139,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         limit: { type: 'number', description: 'Products to scan (default 200, max 500)' },
                     },
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Catalog AI Readiness",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
         ];
     }
@@ -7412,6 +9306,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     stageTimings: result?.write_diag?.stage_timings || result?.stage_timings || null,
                     pluginVersion,
                     mcpVersion: MCP_SERVER_VERSION,
+                    // usage-emitter has accepted and sanitised a `builder` field since it
+                    // was written, and mcp_tool_events.builder was NULL for every one of
+                    // 236,803 events over 30 days, because no call site ever passed it.
+                    // Per-builder quality was therefore invisible in the event stream for
+                    // exactly the builders that carry the most traffic. The plugin already
+                    // returns the builder it acted through; this forwards it.
+                    builder: telemetryBuilderName(result),
                     // The plugin compares a storage signature before and after a write and
                     // says so on the response when nothing moved. It reports that as a
                     // warning on a SUCCESSFUL call, because the call was well formed, so
@@ -8507,6 +10408,22 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     // unambiguous.
                     r.agent_must_escalate = true;
                 }
+                // The plugin used to fail this write outright whenever it could not
+                // read the changed value back off the public page, including when the
+                // page simply did not answer in time. That was 8.9% of live Elementor
+                // element updates, every one of them a write that had already
+                // persisted, and the agent's response to a failure is to retry. The
+                // write now succeeds and says what could not be confirmed, but this
+                // tool has an 81% in-session retry rate precisely because agents do not
+                // read nested fields, so the caveat has to be in the message or it may
+                // as well not exist. Softer than the no-op headline on purpose: nothing
+                // is wrong, the write landed, only the confirmation is missing.
+                else if (r && typeof r === 'object' &&
+                    Array.isArray(r.warnings) && r.warnings.includes('elementor_frontend_unverifiable')) {
+                    const hint = r.frontend_verification_hint || 'The write persisted but Respira could not read the public page to confirm it is visible. Do not retry the same mutation.';
+                    const original = typeof r.message === 'string' ? r.message : '';
+                    r.message = `Note — write saved, publication unconfirmed. ${hint}\n\nOriginal message: ${original}`.trim();
+                }
                 return r;
             }
             case 'wordpress_move_element': {
@@ -8683,7 +10600,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Find Element",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_update_element',
@@ -8735,6 +10658,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value', 'updates'],
                 },
+                annotations: {
+                    title: "Update Element",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_move_element',
@@ -8777,6 +10707,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value', 'target_container_path', 'position'],
                 },
+                annotations: {
+                    title: "Move Element",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_duplicate_element',
@@ -8815,6 +10752,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id'],
                 },
+                annotations: {
+                    title: "Duplicate Element",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_remove_element',
@@ -8858,7 +10802,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value'],
                 },
-                destructiveHint: true,
+                annotations: {
+                    title: "Remove Element",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_batch_update',
@@ -8901,6 +10851,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'operations'],
                 },
+                annotations: {
+                    title: "Batch Update",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_reorder_elements',
@@ -8935,6 +10892,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['post_id', 'container_path', 'new_order'],
                 },
+                annotations: {
+                    title: "Reorder Elements",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Composite Tools ---
             {
@@ -8965,6 +10929,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['title', 'structure'],
                 },
+                annotations: {
+                    title: "Build Page",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_convert_html_to_builder',
@@ -8984,6 +10955,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['html'],
                 },
+                annotations: {
+                    title: "Convert HTML To Builder",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
             },
             {
                 name: 'wordpress_bulk_pages_operation',
@@ -9011,6 +10989,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['page_ids', 'operation'],
                 },
+                annotations: {
+                    title: "Bulk Pages Operation",
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Stock Images ---
             {
@@ -9030,7 +11015,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['query'],
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Search Stock Images",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             },
             {
                 name: 'wordpress_sideload_image',
@@ -9045,6 +11036,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     },
                     required: ['url'],
                 },
+                annotations: {
+                    title: "Sideload Image",
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
             },
             // --- Server Compatibility ---
             {
@@ -9054,7 +11052,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     type: 'object',
                     properties: {},
                 },
-                readOnlyHint: true,
+                annotations: {
+                    title: "Server Compatibility",
+                    readOnlyHint: true,
+                    destructiveHint: false,
+                    idempotentHint: true,
+                    openWorldHint: false,
+                },
             },
             // --- Bricks Deep Tools (20 tools) ---
             ...getBricksTools(),
@@ -9392,6 +11396,21 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 required: ['post_id', ...s.required],
             },
+            /* Every shortcut in this list adds one widget to an existing page, so the
+             * whole family shares one annotation shape: it writes, it cannot clobber
+             * what is already there, and calling it twice adds two widgets. The
+             * annotations have to be minted here rather than in the tools array,
+             * because these 27 tools only exist as the output of this map. */
+            annotations: {
+                title: s.name
+                    .split('_')
+                    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                    .join(' '),
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
         }));
     }
     async run() {